
**************************************************************************
*
* IPAT - Interferometer Threshold Curve Plotter
*
* Stephen R. Whiteley (stevew@srware.com)
*
***************************************************************************

IPAT is a program for displaying the threshold characteristics of two
and three Josephson junction interferometers.  It is free software,
with no guarantees of any sort.

Author: Stephen R. Whiteley (stevew@srware.com)

Release 2.9  9/22/2014
Will now build with gtk+-2.0 if found, previously required gtk+-1.2. 
The pkg-config program must exist and provide cflags and libs for
gtk+-2.0.  If not found, gtk+-1.2 will be used if found.


Introduction
------------

IPAT is a program for plotting the interference threshold curves of
two and three Josephson junction interferometer devices.  IPAT runs
under UNIX with X Windows, or under Cygnus NT with X support.  The
author of IPAT is Stephen R.  Whiteley, and comments or bug reports
should be sent to stevew@srware.com.

Presently, IPAT makes the following assumptions:

 1.  The coupled flux is represented by a current in the loop inductors
     with a transfer ratio set by the user when IPAT starts.

 2.  The gate current injected into the three junction interferometer
     is split between the two branches.  The fraction going to the
     left branch is an input parameter.

 3.  The junctions are perfect RSJ with no coupled flux.


Within these assumptions, the computation is exact, to within an
iteration tolerance of .1 percent.  The algorithms used have been
discussed in the literature, and are implemented in an efficient
manner which provides rapid computation.

References:

Won-Tien Tsang and T. Van Duzer, "The analysis of parallel arrays of
two and three Josephson junctions," J. Appl. Phys., Vol. 46, No. 10,
pp. 4573-4580, October 1975.

  Tsang and Van Duzer outline the Lagrange multiplier method of solving
  the interferometer equations, which is the method used in IPAT for
  three junction interferometers.

R. L. Peterson and C. A Hamilton, "Analysis of threshold curves for
superconducting interferometers," J. Appl. Phys., Vol. 50, No. 12,
pp.8135-8142, December 1979.

  Peterson and Hamilton provide a useful approximate screening
  condition for determining which solutions are unstable.

E. O. Schulz-DuBios and P. Wolf, "Static Characteristics of
Josephson Interferometers," Appl. Phys. (Springer-Verlag), Vol. 16,
pp. 317-338, 1978.

  Shulz-DuBois and Wolf provide detailed analysis of the stability
  criteria.

Gregory S. Lee, "A simple physical principle for determining mode
boundaries in superconducting loop circuits," J. Appl. Phys., Vol 66,
No. 6, 15 September 1989.

  Lee shows an interesting connection between the small-signal
  model of an interferometer circuit and the general equations
  governing the threshold behavior.


The two-junction solution:


  Basic equations:

  (1)  It = Ic1*sin(phi1) + Ic2*sin(phi2)
       (gate current)

  (2)  FLX = phi1 - phi2 + PHI*( L1*Ic1*sin(phi1)  -
           L2*Ic2*sin(phi2) )
       (external flux)

  (3)  1/(Ic1*cos(phi1)) + 1/(Ic2*cos(phi2) + PHI*(L1+L2) = 0
       (The auxiliary condition)
       This expression can be derived by introducing a Lagrange
       multiplier m, and setting I~ = It + m*FLX.  Equating
       dI~/dphi1 = 0 and dI~/dphi2 = 0 yields (3).

  where
    
    It   threshold gate current
    FLX  externally applied flux
     
  There are two junctions, one with phase phi1 and critical current Ic1,
  and similar for the second junction.  The loop inductance is split
  between L1 and L2, whth the gate current driving the connection point.
  L1 connects to J1, and L2 connects to J2.

  The algorithm is to simply loop over phi1, then again over phi2 to
  better fill in the curve, using (3) to get the other angle. Equations
  (1) and (2) provide a locus of points which define the threshold curve.


Three junction solution:

  Basic equations:
  sN = IcN*sin(phiN)
  cN = icN*cos(phiN)

  (1)  It = s1 + s2 + s3
          = Il + Ir, Il/It = C  ( C is splitting fraction )
       (gate current)

  (2)  f1 = phi1 - phi2 + PHI*(L1*s1 - L2*(C(s2 + s3) + (C-1)*s1)) + Order1
       (left loop flux)

       f2 = phi2 - phi3 + PHI*(L3*((1-C)*(s1 + s2) - C*s3) - l4*s3) + Order2
       (right loop flux)

  (3)  I~ = It + A*(f1 terms) + B*(f2 terms)
       (lagrange multipliers)

  (4)  Partial derivatives

       phi1:
       c1 +
          A * (1 + PHI*L1*c1 + (1-C)*PHI*L2*c1) +
          B * (1-C)*PHI*L3*c1 = 0

       phi2:
       c2 -
          A * (1 + C*PHI*L2*c2) +
          B * (1 + (1-C)*PHI*L3*c2) = 0

       phi3:
       c3 -
          A * C*PHI*L2*c3 -
          B * (1 + PHI*L4*c3 + C*PHI*L3*c3) = 0

  (5)  FLX = f1 + f2
       (total external flux)

  (6)  (L3+L4)*f1 - (L1+L2)*f2 = 0
       (assume the flux is coupled through the loop inductance)
       A common control line divides the flux between the two loops as
       above.


We loop over phi1, then phi2, and finally phi3, to ensure that the
curves are filled in.  Given one angle, (4) and (6) are used to find
the other two, using a Newton-Rhapson numerical solution algorithm.
(1) and (5) provide the locus of points which represent the threshold.
Before plotting, we discard any points where

    PHI*Ic1*cos(phi1)*(L1+L2) < -1, or
    PHI*Ic2*cos(phi3)*(L3+L4) < -1.

These points represent nonphysical solutions.  The above conditions
are not rigorously sufficient to eliminate all such solutions, but
in practice there does not seem to be a problem.

This process is repeated with Order1 set to 2*PI to get the secondary
thresholds (where the two loops differ by one flux quantum), and Order2
is set to -2*PI and the process is again repeated to get the third order
thresholds (loops differ by two flux quanta).


Building and Installing IPAT
----------------------------

1.  Configure:  The script has the following syntax, where the square
    brackets mean "optional"

    ./configure [--prefix=/some/path] [--enable-gtk[=/gtk/path]]

    Most commonly, one would just type "./configure".

    The --prefix=/some/path argument will direct installation into
    /some/path/bin rather than the default /usr/local/bin.

    The --enable-gtk[=/gtk/path] enables use of the gtk+ toolkit under
    Microsoft windows (MinGW), otherwise the native Win32 system is
    used (functional but ugly).  Under all other operating systems,
    gtk is required, so that the argument is ignore except to set
    a path.

    In any case, either the original gtk+-1.2, or the newer gtk+-2.0
    gtk libraries can be used.  If no /gtk/path is given, the build
    system will look for the programs "pkg-config" (for gtk+-2.0) then
    "gtk-config" (for gtk+-1.2) along the user's shell search path. 
    Under Windows, the build system will instead look for the "gtk2
    bundle" package mentioned below.  If a /gtk/path is given, the
    build system will look in that directory.

    Note that for a successful build, the "development" part of the
    gtk+ library (and sub-libraries) must be installed.  It may be a
    necessary prerequisite to install a distribution with a name
    starting with something like "gtk2-devel".  Of course, the usual
    program development toolchain found on most Linux-like systems
    must be available (e.g., icode with the command-line tools is
    needed on Apple).

    Under Windows, the MinGW compiler and toolchain must be installed,
    along with Cygwin for bash and make.  One can probably build the
    program directly under Cygwin if desired, with or without the
    Cygwin gtk libraries.

    With MinGW, the "gtk2-bundle" supplied by Whiteley Research as
    free software can be used.  Simply download and install the
    package.  The same package is used by Whiteley Research products. 
    If installed in the default location, one can type "./configure
    --enable-gtk" in a shell pointing to the MinGW tools to build the
    gtk version.

    Note that prebuilt packages for Windows are available.

    There is also a "gtk2-bundle" available for Apple OS X, which can
    be installed and linked to.  Similar to Windows, this package is
    free software from Whiteley Research, and is used with the
    products.  One can also use MacPorts or similar to obtain gtk.

2.  Compile: Type

    make

    The three source files will be compiled and linked into the ipat
    program.  If this does not happen due to an error, you will have
    fun figuring out the problem.

3.  Install: Become root, and type

    make install

    This simply copies the program to /usr/local/bin, or the
    other location if --prefix was given.

4.  Read the ipatrc file note, and if desired install the file in your
    home directory as per instructions.  Under Windows, the home
    directory can be specified by setting the $HOME environment
    variable to a directory path.  The .ipatrc file will also be found
    if located in the current directory.

If problems, contact stevew@srware.com.


Running IPAT
------------

From a command line, type "ipat".  Any words following "ipat" on the
command line are expected to be a path to a file in the format of the
output file from Jspice3/WRspice operating range analysis.  The pass
or fail points from the file will be plotted along with the
interference pattern (see Load Points below).  A window will appear,
containing some input areas, and graphical areas for the plot and a
schematic.  There is a menu bar along the top, containing a "WR"
button, and File, Options, and Help menus.

The WR button cycles through four different horizontal scale factors
for the plot, allowing the user to select the number of periods to
display.

The File menu contains the following selections:

  Save

    The Save button in the File menu brings up a dialog asking for a
    name to save the current data set under.  This name can be any
    name, but it can not start with the character '#', and it can't
    include white space.  The data set will be saved in the file
    ".ipat.data", in the user's home directory.  If the home directory
    can't be determined, such as under Windows if the environment
    variable $HOME is not defined to a directory path, a file named
    ipat.data in the current directory will be used.  In either case
    the file will be created if it does not already exist.  The format
    is very simple:  each line contains the name, followed by the
    number of junctions, followed by the nine values from the input
    entry widgets, top to bottom as on-screen.  Note that some of
    these values are not really used for two junctions, but some
    numeric value must be present in that position as a place-holder. 
    If the given name is already present, the new data set will
    overwrite the old.

  Recall

    Pressing the Recall button in the File menu will produce a menu
    containing the names of all saved parameter sets.  Selecting one of
    the entries will load those values into ipat, and update the display.

  Delete

    The Delete button in the File menu will prompt for a dataset name to
    delete from storage.  The response should be the name of a parameter
    set previously stored.

  Load Points
 
    This allows a "points" file to be read.  The points found in the
    file will be added to the plot.  The file format is the
    Jspice3/WRspice operating range output format.

  Print

    This brings up a pop-up which controls printing the current
    display.

  Quit

    Exit IPAT.

The Options menu contains the following selections:

  Three Junctions

    When set, a three-junction device will be plotted.  When unset, a
    two-junction device will be shown.

  Phase Plot

    When set, a phase plot will be presented.  When unset, a threshold
    plot will be presented.

  Show Negative X

    When set, both positive and negative control currents will be
    shown.  When unset, only positive control currents will be shown.

  Show Negative Y

    When set, both positive and negative threshold voltages will be
    shown.  When unset, only positive threshold voltages will be
    shown.

  Suppress Axes

    When set, the axes and grid points will not be shown.

  Suppress Secondary

    When set, the secondary contours of three-junction devices will
    not be shown.

  Suppress Tertiary

    When set, the tertiary contours of three-junction devices will not
    be shown.

  Plot Fail Points

    If plotting points from a file (Load Points in File Menu) show the
    fail points.

  Show Marker

    Enables a marker and printout of the cursor coordinates.  Retire
    the marker by pressing any key.  The left mouse button marks a
    location which is used as a reference for the coordinate printing,
    which can be deleted with the right button (i.e., go back to
    absolute coordinates).

The Help menu contains the following selections:

  Help

    Bring up a window containing a a description of the program
    features.

The best way to learn IPAT, and to learn about interferometers, is to
experiment.  Have fun!

