Short readme for the JMATRIX program
------------------------------------

This document contains only the short information about unpacking, 
compiling and running the JMATRIX program. Full documentation 
is provided in the jmatrix.pdf file.

Unpacking
---------

Gunzip and untar the provided archive using the following commands:

gunzip jmatrix.tar.gz (or gzip -d jmatrix.tar.gz)
tar -xf jmatrix.tar

(you've probably done it already since you are reading this readme). 
Source files are located in the "jmatrix/source" directory. 
Documentation is placed in the  "jmatrix/doc" directory. 
Executables, input and output files are stored in the "jmatrix/bin" directory.
Executables for few operating systems are provided in the package, 
but is strongly recommended to build the JMATRIX program from the provided 
Fortran 90 sources.

Compilation
-----------

You need Fortran 90 and Fortran 77 compilers to build the JMATRIX program 
from the sources. 
Change the current directory to the "jmatrix/source". Edit the file "makefile" 
and replace values of the variables FCOMP90 and FCOMP77 with the 
executable names of your Fortran 90 and Fortran 77 compilers, respectively. 
Usually, you can use Fortran 90 compiler to compile the Fortran 77 code, 
but, in some cases, distinction between these can improve the overall 
performance. 
If necessary, edit the variables FCFLAGS90 and FCFLAGS77, their values 
are the parameters passed to compilers. The most common application 
for these variables is to provide the code optimization switches. 
When edit is complete, you can start the compilation process by typing 
the command "make". Created executable ("jm" in Unix, "jm.exe" in Windows) 
will be moved to the directory "jmatrix/bin".

If you use any of the following compilers:
- Portland Group PGI Fortran Compiler,
- VAST Fortran Compiler,
- Intel Fortran Compiler,
- Compaq Visual Fortran,
you can use included makefiles, prepared specially for them by typing command 
make -f makefile.[pgi][win.pgi][vast][ifc][win.cvf]
with a proper suffix, or simply rename the proper file to "makefile" 
and then run "make".

If you wish to delete all files created during compilation (except the main 
executable), run the command "make clean".


Running the program
-------------------

Change the current directory to the jmatrix/bin and run the program 
"jm" (or "jm.exe"). You can also run program using the provided 
executables ("jm-lin" or "jm-win.exe").

Input file
----------

Default name of the input file is jm.inp. One can select another input 
filename at start of  the program execution. The input file consist 
of a set of lines in the following form:

; comment
keyword = value   ; comment

Blank lines, lines beginning with ";" and lines without proper keyword 
are ignored. Keywords and values are case sensitive, their order in a file 
is arbitrary. There must be at least one space before and after the "=" sign 
and before the ";" sign (except the case when the whole line is a comment).

Valid keywords are:

estart   - bottom bound of the projectile energy (real number, required keyword)
eend     - upper bound of the projectile energy (real, required)
estep    - energy step (real, default is (eend-estart)/10)
l        - orbital quantum number of the projectile (integer, required)
kappa    - quantum number of the projectile 
           (integer, required if relativistic scheme, kappa=l or kappa=-l-1)
lambda   - scaling parameter (real, lambda <> 0.5, default is lambda = 1.0)
basis    - Basis set: {gauss, laguerre} (char, required)
scheme   - scheme: {relativistic, non-relativistic} (char, required)
pot_type - potential type: {well, coulomb, other} (char, required)
v_light  - speed of light: {finite, infinite} (char, default is finite)
nstart   - initial value of N (integer, default is nstart = 1)
nend     - final value of N (integer, required)
screen   - display (or not) results on screen (logical, default is .T.)
shift    - shift (or not) results to range [0, pi] (logical, default is .F.)
v0       - depth of the potential square-well (v0 < estart)
           (real, required if pot_type = well)
a        - left bound of the potential square-well 
           (real, required if pot_type = well)
b        - right bound of the potenial square-well 
           (real, required if pot_type = well)
r0       - truncating parameter of the Coulomb potential
           (real, required if pot_type = coulomb)
z        - parameter of the Coulomb potential
           (real, required if pot_type = coulomb)
alpha    - alpha parameter of the Coulomb potential
           (real, required if pot_type = coulomb)


Pre-defined potentials
----------------------

Potential square-well:

     a     b
 ____       _____ V=0
     |     |
     |     |
V=v0 |_____|


Truncated coulomb potential:

V(r) = -z/(ralpha) (truncated at r = r0, so then V(r > r0) = 0)

Other potential
---------------

If you wish to use your own potential, edit the file jm_v.f90 and provide
the proper formula in line 32. Then recompile the code, set the pot_type=other 
in the input file, and run the program.

Output files
------------

There are several output files created during execution of the JMATRIX program.
Default names of the output files are <root> and <root>-en. The default 
<root> name is jm.out and can be changed during execution of the program. 
The third output file is saved.vn -  this name can not be changed.