README for bfield_poisson
8/14/2009  David Lawrence


INTRODUCTION
==================
This directory contains files that can be used to generate
a magnetic field map of the GlueX solenoid using the Poisson
Superfish program suite from LANL. The poisson software runs
on the Windows platform, but is compatible enough that it
can be run via the WINE package.

The software may be obtained via the LANL website at the URL
below, but when I did it (8/13/2009) the final link to the
installer was broken. For this reason the additional links
are provided below to access the poisson software installer.
The authors would like users to register so you may decide
to do that anyway and then download from an alternative URL
below.

Official LANL Download Area (final installer link broken):
http://laacg1.lanl.gov/laacg/services/download_sf.phtml

Official LANL site: direct link to installer binary
http://laacg1.lanl.gov/software/PoissonSuperfish/PoissonSuperfish_7.18.exe

Hall-D Website:
http://www.jlab.org/Hall-D/software/PoissonSuperfish_7.18.exe


DESCRIPTION OF RELEVANT PROGRAMS:
=================================
Poisson is actually just one of a collection of programs.
The shortest sequence of programs that must be run in
order to generate a map that can be used by the Hall-D
simulation/reconstruction code is:

AUTOMESH.EXE
POISSON.EXE
SF7.EXE
poisson2calibDB.pl (on a machine that has perl installed)

The AUTOMESH.EXE program takes as input a file with extension
.am and produces a file with extension .t35. The input file
is ASCII and contains parameters specifying the mesh density
and the coil cross-sections and current flux through them (as
well as some other geometry/materials). The output is a binary
file with extension .t35. This serves as the input (and output)
to the POISSON.EXE program. The AUTOMESH.EXE program takes
only a few seconds to run on my laptop.

The POISSON.EXE program reads in a file with .t35 extension
and appends the details of the magnetic field solution to
it so that the same file is used for both input and output.
This takes around 2 minutes to run on my laptop.

The SF7.EXE program reads in the .t35 file as input and
creates a file Outsf7.txt as output. Instructions are read
either from a file with a .IN7 extension (same base name
as .t35 file) or it will pop up a GUI to get the parameters
for the output. For our purposes, we generally want a grid.
The file gluex_sol_04.in7 in this directory gives an
example suitable for conversion to our calibDB format
using the poisson2calibDB.pl script. 

The poisson2calibDB.pl script is a perl script written
just to convert a file from the format SF7.EXE generates
to the format needed for the Hall-D simulation/reconstruction
software. If you run all of the other code on a Windows
machine that does not have perl installed, then you
will need to move the Outsf7.txt file to a machine
that does in order to run this script.

The WSFPLOT.EXE program is also useful since it reads
in a .t35 file and draws it graphically in an interactive
GUI. This lets you examine both the mesh and the field
values quickly.

Finally, several run_XXX.bat files exist here that can be used
to run or just provide examples of how to run the above
programs (with the exception of possion2calibDB.pl).


HOWTO GENERATE a field map:
=============================
The easiest thing to do is simply run the run_all.bat script.
This will run the programs needed to generate the OUTSF7.TXT
file. Note that the programs will run as Windows programs
meaning control returns immediately to the MS-DOS prompt
(and the therefore the batch script) immediately after each
program is launched and before it has completed. It is due to
this that the batch script has PAUSEs built in so that the
user can tell it when each program is finished before running
the next program which will depend on its input.

Copy the OUTSF7.TXT file to a unix machine and run the poisson2calibDB.pl
script on it using the OUTSF7.TXT filename as input.