release of new version (completely rewritten in Python)

.gitignore

@@ -1,13 +1,4 @@
-*.o
-*.mod
+*.pyc
+__pycache__
 
-alcon
-alcon.log
 output
-
-testcsp
-testcsp.log
-fexact.dat
-ftab.dat
-fip.dat
-

README.md

@@ -1,14 +1,16 @@
 ALCON
 =====
-version 2013-09-04 15:21:30-04:00
+version 2014-05-24 13:22:42-04:00
 ---------------------------------
 
-ALCON is a code for solving ideal MHD Alfven continua in tokamaks,
-i.e., Eq. (10) in
-[Physics of Fluids 29, 3695 (1986)](http://dx.doi.org/10.1063/1.865801),
-using a poloidal-spectral method described in Appendix A in
-[Nuclear Fusion 52, 043006 (2012)](http://wdeng.info/?p=117).
-When referencing ALCON in a publication, please cite:
+ALCON has been rewritten in Python.  All users including those of the former
+Fortran version are encouraged to read through this README to get familiar with
+the new Python version.
+
+ALCON is a code for solving ideal MHD Alfven continua in tokamaks, i.e.,
+Eq. (10) in [Physics of Fluids 29, 3695 (1986)][], using a poloidal-spectral
+method described in Appendix A in [Nuclear Fusion 52, 043006 (2012)][].  When
+referencing ALCON in a publication, please cite:
 
 	@ARTICLE{Deng2012b,
 		author = {W. Deng and Z. Lin and I. Holod and Z. Wang and Y. Xiao and H. Zhang},
@@ -21,6 +23,9 @@ When referencing ALCON in a publication, please cite:
 		doi = {10.1088/0029-5515/52/4/043006}
 	}
 
+[Physics of Fluids 29, 3695 (1986)]: http://dx.doi.org/10.1063/1.865801
+[Nuclear Fusion 52, 043006 (2012)]: http://wdeng.info/?p=117
+
 
 Copying
 -------
@@ -42,21 +47,20 @@ along with ALCON.  If not, see <http://www.gnu.org/licenses/>.
 System requirements
 -------------------
 
-ALCON requires MPI-2, [PETSc](http://www.mcs.anl.gov/petsc/) and
-[SLEPc](http://www.grycap.upv.es/slepc/) with complex scalars.  ALCON has been
-tested with [MPICH2](http://www.mcs.anl.gov/research/projects/mpich2/) 1.4,
-[OpenMPI](http://www.open-mpi.org/) 1.5, PETSc and SLEPc 3.3.  Although with a
-few tweaks ALCON can probably work with other versions of PETSc and SLEPc, it
-is recommended to use PETSc and SLEPc 3.3.
+ALCON requires:
 
-ALCON also requires a Fortran 95 compiler for compilation.  ALCON has been
-tested with [GNU Fortran](http://gcc.gnu.org/fortran/) 4.6.
++ [Python](https://www.python.org/) 2 (2.7+) or 3 (3.4+)
++ [NumPy](http://www.numpy.org/) 1.8+
++ [SciPy](http://www.scipy.org/scipylib/index.html) 0.13+
+
+Additionally, [matplotlib](http://matplotlib.org/) 1.3+ is recommended for
+quickly plotting solved continua.
 
 Unless you keep excessive (100+) poloidal m-harmonics and want excessive high
 radial resolution (solving 5000+ radial grid points), ALCON should be able to
 finish a run within half an hour on any desktop that has two or more physical
-cores.  In most practical cases, ALCON can finish a run within a few minutes on
-a desktop within a few years old.
+cores.  Running the default case on an Apple Mac Mini 2011 takes about 14
+minutes with a single process and about 10 minutes with two processes.
 
 
 Usage
@@ -65,44 +69,77 @@ Usage
 ### Know about the files
 
 + `README.md` -- This instruction.
-+ `Makefile` -- For using GNU make to compile and run ALCON.
-+ `alcon.F90` -- The main program file.
-+ `alcon_input.F90` -- Module for managing input parameters. Change input
-parameters in this file.
-+ `alcon_eqdata.F90` -- Module for managing equilibrium data.
-+ `alcon_solver.F90` -- Module for solving Alfven continua.
-+ `alcon_output.F90` -- Module for managing output data and writing to output
-files.
-+ `cspline_petsc.F90` -- Module for cubic spline interpolation using PETSc.
-+ `testcsp.F90` -- A small program to test `cspline_petsc.F90`, not an
-essential part of ALCON, but if you are interested in playing with the cubic
-spline module, help yourself.
++ `COPYING` -- The license (GNU General Public License) for ALCON.
++ `alcon.sh` -- A bash script for conveniently launching alcon.py without the
+need to type all the input parameters in the command line.  This script can be
+used as an input file.
++ `alcon.py` -- The main program file.
++ `alcon_input.py` -- Module for managing input parameters.
++ `alcon_eqdata.py` -- Module for managing equilibrium data.
++ `alcon_solver.py` -- Module for solving Alfven continua.
++ `alcon_output.py` -- Module for writing solutions to output files.
++ `wctimer.py` -- Module for a wall-clock timer.
++ `alcon_plot.py` -- Plotting utility for plotting output data from ALCON.
++ `alcon_plot_input.py` -- Module for managing input parameters for the
+plotting utility.
++ `alcon_plot_core.py` -- Module for core functionalities of the plotting
+utility.
 + `alcon.dat` -- A sample equilibrium data input file.  The equilibrium is
-taken from [Physics of Plasmas 17, 112504 (2010)](http://wdeng.info/?p=37).
-This file is for testing when you use ALCON for the first time.  For practical
-use, you want to replace this file by your own `alcon.dat` file generated from
-your equilibrium.  See `acdgen_sample.F90` for a sample subroutine to generate
-`alcon.dat`.
+taken from [Physics of Plasmas 17, 112504 (2010)][].  This file is for testing
+when you use ALCON for the first time.  For practical use, you want to replace
+this file by your own `alcon.dat` file generated from your equilibrium.  See
+`acdgen_sample.F90` for a sample subroutine to generate `alcon.dat`.
 + `profile_sa.dat` -- A sample equilibrium profiles for solving a simple
 analytic equilibrium.  The profiles are taken from
-[Physics of Plasmas 17, 112504 (2010)](http://wdeng.info/?p=37).  This file is
-for testing when you use ALCON for the first time.  For practical use, you want
-to replace this file by your own `profile_sa.dat` file.  See next section for
-preparing your own `profile_sa.dat`.
+[Physics of Plasmas 17, 112504 (2010)][].  This file is for testing when you
+use ALCON for the first time.  For practical use, you want to replace this file
+by your own `profile_sa.dat` file.  See next section for preparing your own
+`profile_sa.dat`.
 + `acdgen_sample.F90` -- A sample subroutine to show how to generate
 `alcon.dat`.
 
+[Physics of Plasmas 17, 112504 (2010)]: http://wdeng.info/?p=37
+
+
+### Running
+
+The main program file is `alcon.py`.  To launch it, you can execute
+`python alcon.py [options]`, or simply `./alcon.py [options]` if your system
+supports direct script execution (with the script parser specified by the
+[shebang][] in the script; supported by most UNIX and Linux systems including
+Mac OS X) and the execution permission is granted for `alcon.py`.  To see all
+the available `[options]`, use the `-h` option, i.e., execute
+`python alcon.py -h`.  First-time user can simply run `python alcon.py` to try
+out ALCON with default parameters and a sample tokamak equilibrium.  To get
+meaningful results from the execution of `alcon.py`, careful input preparation
+is needed.
+
+Note that the above paragraph assumed the Python interpreter to be `python`.
+If this is not the case, you need to replace the interpreter specifier
+accordingly.  For example, if you use Python 3 and its interpreter is named
+`python3` instead of `python`, you need to execute
+`python3 alcon.py [options]` instead of `python alcon.py [options]`, or replace
+the shebang line `#!/usr/bin/env python` by `#!/usr/bin/env python3` in
+`alcon.py` for direct script execution.  This also applies to the plotting
+utility `alcon_plot.py`.
+
+[shebang]: http://en.wikipedia.org/wiki/Shebang_(Unix)
+
 
 ### Input preparation
 
-ALCON reads input parameters from `alcon_input.F90`, so set your input
-parameters in this file.  Detailed description of each parameter is included in
-the comments in `alcon_input.F90`.
+ALCON (`alcon.py`) reads input parameters from the command line.  Execute
+`python alcon.py -h` to see all the command line parameters.
 
-Depending on the eqtype parameter set in `alcon_input.F90`, ALCON reads
-equilibrium data from additional input files.  For currently implemented
-options for eqtype, ALCON may read from `alcon.dat` or `profile_sa.dat` for
-equilibrium data.  ALCON comes with a sample of each of these two files.
+A bash script `alcon.sh` is provided for easily setting input parameters.  You
+can directly edit the input parameters in this file, and then execute this file
+(`bash alcon.sh` or `./alcon.sh`) in the command line to launch ALCON with your
+specified input parameters.
+
+Depending on the parameter passed to the `--eqtype` option, ALCON reads
+equilibrium data from additional input data file.  For currently implemented
+parameters for `--eqtype`, ALCON may read from `alcon.dat` or `profile_sa.dat`
+for equilibrium data.  ALCON comes with a sample of each of these two files.
 
 To prepare your own `alcon.dat`, see `acdgen_sample.F90` for a sample
 subroutine to generate `alcon.dat`.
@@ -112,54 +149,72 @@ one real number, which is the inverse aspect ratio a/R0; the second line puts
 two integers `nrad` and `nprofile`, `nrad` being the number of radial grid
 points for the profiles, `nprofile` being the number of profiles (for current
 version always put `nprofile` to be 4); starting from the third line is a
-`nrad * nprofile` matrix giving the profile data.  The first column is the radial
-coordinate r/a.  The second column is the q-profile.  The third column is the
-pressure profile normalized as: (4 pi gamma P / B^2), where gamma is the
+`nrad * nprofile` matrix giving the profile data.  The first column is the
+radial coordinate r/a.  The second column is the q-profile.  The third column
+is the pressure profile normalized as: (4 pi gamma P / B^2), where gamma is the
 specific heat ratio, P is the plasma pressure, B is the on-axis magnetic field,
 and P and B are in CGS units.  The fourth column is the mass density normalized
 by proton mass times on-axis electron density (Eq. (A.35) in
 [Nuclear Fusion 52, 043006 (2012)](http://wdeng.info/?p=117)).
 
 
-### Compilation
+### Output data and plotting
 
-It is recommended to use GNU make (or a compatible alternative) to compile the
-code with the included Makefile.  Before compiling, open the Makefile and go to
-the place after the license part, you will see a few parameters, such as
-compiler name, compiling options, MPI executor, etc., defined there.  Adjust
-them according to your system environment.  After saving your adjustments, you
-can compile ALCON by executing in the terminal:
+All output data files are put in the sub-directory specified by the `--dirout`
+option.  Note that if the specified directory preexists, ALCON will exit with a
+"file exists" error, unless the `--erasedirout` option is specified, in which
+case the preexisting directory will be erased.
 
-	make
+A plotting utility (`alcon_plot.py`) is provided for plotting and generating
+plotting scripts for other visualization softwares.  It supports these
+operations:
 
-To remove the compiled binary and all other temporary files during compilation,
-execute:
++ plotting on screen or saving a .png or .pdf figure through matplotlib;
++ generating a .m script for MATLAB;
++ generating a .pro script for IDL;
++ generating a .gp script and a Makefile for gnuplot.
 
-	make clean
+Run `python alcon_plot.py -h` for detailed usage information.  First-time user
+can simply run `python alcon_plot.py --dirout <directory of ALCON output>` to
+get the continuum plot on screen, then gradually try out other options.
 
 
-### Running
+Known issue
+-----------
 
-After successfully compiling ALCON, and making sure your MPI environment is
-correctly configured, you can then run ALCON by executing:
+ALCON can run in parallel by specifying an integer larger than 1 to the `-n`
+option.  The parallelization is implemented using the multiprocessing module in
+the Python Standard Library.  However, on Mac OS X, the subprocesses of a
+program that is parallelized in this way and has certain NumPy and SciPy
+function calls would crash, if NumPy and SciPy are built with
+[Apple's Accelerate Framework][].  More information about this issue can be
+found at these links:
 
-	make run
++ <https://github.com/numpy/numpy/issues/654>
++ <http://mail.scipy.org/pipermail/numpy-discussion/2012-August/063590.html>
 
+This issue does not apply if NumPy and SciPy are built with [OpenBLAS][].  If
+you use [Homebrew][] to install NumPy and SciPy, you can choose to build them
+with OpenBLAS by passing the `--with-openblas` option:
 
-### Output data and plotting
+	brew install numpy --with-openblas
+	brew install scipy --with-openblas
 
-All output data files are put in the `output` sub-directory.  If you choose to
-generate a plotting script (`outformat` option in `alcon_input.F90`), it is
-also put in the `output` sub-directory.  Then you can use the corresponding
-plotting software to produce an Alfven continuum figure.
+The above commands may complain:
 
-**When you execute `make run`, the content of the output sub-directory will be
-erased before ALCON runs.  If you think the output data files are useful, move
-them immediately to a safe place, or simply rename the output sub-directory.**
+	Error: Operation already in progress for openblas
+	Another active Homebrew process is already using openblas.
+	Please wait for it to finish or terminate it to continue.
 
-You can also manually erase the output sub-directory by executing:
+To work around this, run `brew edit numpy`, then the NumPy formula would be
+opened in the default text editor.  In the editor, replace
+`homebrew/science/openblas` by `openblas`, save and quit.  Then run
+`brew edit scipy` and do the same replacement.  Afterwards, run the above
+commands to install NumPy and SciPy.
 
-	make cleanoutput
+[Apple's Accelerate Framework]: https://developer.apple.com/library/mac/documentation/Accelerate/Reference/AccelerateFWRef/_index.html
+[OpenBLAS]: http://www.openblas.net/
+[Homebrew]: http://brew.sh/
 
 
 Contact
@@ -184,11 +239,10 @@ ALCON was originally developed when I was a graduate student at University of
 California, Irvine, where my research was supported by the U.S. Department of
 Energy (DOE) SciDAC Center for Gyrokinetic Simulation of Energetic Particle
 Turbulence and Transport (GSEP).  The development continued after I became a
-research physicist at Princeton Plasma Physics Laboratory, where my research
-was supported by the U.S. DOE SciDAC Center for Nonlinear Simulation of
-Energetic Particles in Burning Plasmas (CSEP).  I would like to acknowledge
-useful discussions with Eric Bass, Guo-Yong Fu, Zhihong Lin, Don Spong, Xin
-Wang, Zhixuan Wang, and Huasen Zhang.
+postdoc at Princeton Plasma Physics Laboratory, where my research was supported
+by the U.S. DOE SciDAC Center for Nonlinear Simulation of Energetic Particles
+in Burning Plasmas (CSEP).  I would like to acknowledge useful discussions with
+Eric Bass, Guo-Yong Fu, Zhihong Lin, Don Spong, Xin Wang, Zhixuan Wang, and
+Huasen Zhang.
 
 Wenjun Deng
-