This is a sample program for evolving the Schroedinger equation via
split-operator Fourier transform methods.  The example is the evolution
of a Gaussian wave packet in a harmonic potential.
All compilable code here is written in Fortran 90

For assistance with running this code, contact the author, Daniel Steck,
at <dan at steck dot us>.

This code is provided as-is, without warranty; you should thoroughly
test it before trusting it.  This code is free for non-commercial use.


************************************************************************

The contents of this directory are:

README: this file

sch1d.f90: the main program file; look at this for an overview of the
           simulation.

globals.f90: globally declared parameters, especially those needed
             by the split-operator evolver routines, and things
             like the working precision of the calculation.

param_parser.f90: fetches parameter values for the simulation from 
                  a parameter file (specified on the command line)

output.f90: routines to output results of simulations to output files

splitop_evolver.f90: routines to implement split-operator evolution methods;
                     also, the potential energy function is specified here.

ffts.f90: fast Fourier transform library for use by splitop_evolver and output 

timing.f90: routines to measure and report elapsed time

utilities.f90: various routines needed for parsing parameters and file names

makeanm: Perl script to take data from sample run with 'sample.param'
           and generate an animated gif of the x distribution with time.
           Requires the ImageMagick and gifsicle utilities to be installed.
           To use this for your own nefarious purposes, change the variables
           near the top of the file in ways that will (I hope) be obvious.

makeanmp: same as makeanm, but for the p distribution

graph_template.eps: required file used by makeanm and makeanmp (should be in
                    same directory that you're running the scripts from)

testscript.m: a script that runs in MATLAB or Octave to take the
              results generated by ruscript, calculate the global
              errors for the integration for different step sizes,
              plot them, and fit the global errors to empirically
              determine the global convergence order of the integration

Makefile: makefile for sch1d.f90, assuming g95 is the system compiler


************************************************************************

See the individual files for further documentation.

To modify this code for other problems, concentrate on the following
files:

sch1d.f90: for overall stuff (e.g., to manage more complicated operator
           splittings)
globals.f90: for global variables
param_parser.f90: to add/change input parameters
output.f90: to change what data are output
splitop_evolver.f90: to change the Schroedinger equation potential V(x,t)

************************************************************************

To summarize: download and unpack the source tarball, and enter the source
directory.  Now build the source:

  make

and run it with the parameters in sample.param:

  ./sch1d sample.param

alternatively, just run it and enter 'sample.param' at the prompt:

  ./sch1d
  Enter name of parameter file: sample.param

now look at some things; for example, plot <x> vs. t in gnuplot
by saying "plot 'sample.avg.txt' us 1:2 w l".   Look in output.f90
to see what the other columns in this data file mean.

Also, to animate the wave function (actually |psi(x,t)|^2), try this 
script on one of the lab machines:

  ./makeanm

Ideally this will make the animation sample.xdist.gif, as well as
another .gif file for the first frame of the animation.
Play it in Quicktime Player:

  open -a quicktime\ player sample.xdist.gif

or in any web browser.  Also, 

  ./makeanmp

will make the corresponding animation for the momentum-space
wave function.

Finally, to clean up:

  make clean && rm -rf *.txt *.gif

************************************************************************