1D OpenMP Particle-in-Cell (PIC) BEPS1 codes
by Viktor K. Decyk, UCLA
copyright 1994-2017, regents of the university of california

These codes are part of a set of 1d PIC codes for educational use.  They
are designed for Linux using OpenMP but will also compile for Mac OS X.
OpenMP is used for parallelization.

A Software License for use of this code is in the document:
Documents/License(CommercialReservation)

A description of the design of these codes and its components is in the
document:
Documents/BEPS1Design.pdf

A description of the capabilities of these codes and its components is
in the document:
Documents/BEPS1Overview.pdf

Details about the mathematical equations and units used in this code is
given in the document:
Documents/UPICModels.pdf.

A description of the input parameters to these codes and their default
values are in the document:
mbeps1.source/input1mod.f90

There are 3 Fortran reference codes for electrostatic, electromagnetic,
and darwin models, called mbeps1, mbbeps1, and mdbeps1, respectively.

There are 3 Python scripts for electrostatic, electromagnetic, and
darwin models, called mbeps1.py, mbbeps1.py, and mdbeps1.py,
respectively.  They require 3 dynamic libraries, libmpush1.so,
libmbpush1.so, and libmdpush1.so, respectively, which are located in
mbeps1.source.  These python scripts currently only work in single
precision.  They work with both Python2 and Python3

The makefile is setup to use gcc and gfortran with Linux.

To compile the fortran codes in the current (mbeps1) directory, execute:

make

To compile just one, execute:

make program_name

where program_name is either: mbeps1, mbbeps1, or mdbeps1

To execute, one first needs to copy an input file from the Examples
directory to the current directory.  The files for the electrostatic
code are in the Examples/ES directory, those for the electromagnetic
code are in the Examples/EM directory, and those for the darwin code
are in the Examples/Darwin directory.  To run the electrostatic code
with the plasma wave example, type:

cp Examples/ES/input1.plasma input1

./program_name

where program_name is either: mbeps1, mbbeps1, or mdbeps1

To delete compiled libraries (.o files) and the executables, execute:

make clobber

For more details about compilation, including use of double precision
and debug graphics, see mbeps1.source/README

To compile the Python libraries in the current (mbeps1) directory,
execute:

make python

To execute the scripts, then type:

python program_name

where program_name is either: mbeps1.py, mbbeps1.py, or mdbeps1.py

If files are generated by the reference applications, sample programs
to read them is available in the Directory ReadFiles.  A Fortran program
called diag1 is available to read the data.  This program can be used to
read scalar, vector, fluid, velocity, test particle trajectory or phase
space data.  The program diag1 calls lower level procedures called
pcreadf1, pvcreadf1, pflreadf1, pfvreadf1, ptreadf1 and psreadf1 located
in the ReadFiles directory, each of which reads one of six types of
data.  Currently these are just skeleton codes which processes data
which have been written by the reference applications and creates
arrays available for further processing.

To compile this code in the current (mbeps1) directory, execute:

make readf

To execute this program, type:

./diag1

This program will examine a data metafile created by the simulation
(consisting of namelists) called diag1.idrun, where idrun is the run id
for that run, will determine which diagnostics were created, and will
ask the user which diagnostic to examine.  

To delete compiled libraries (.o files) and the executable, execute:

make readfclobber

It is also possible to call executable versions of the low level
procedures directly by first compiling them with:

make readfall

Then executing

./ReadFiles/program_name

where program_name is of the the following:
pcreadf1, pvcreadf1, pflreadf1, pfvreadf1, ptreadf1 and psreadf1

There is also a Python script available to read the data, diag1.py,
located in the mbeps1 directory.  This in turn calls lower level
scripts called pcreadf1.py, pvcreadf1.py, pflreadf1.py, pfvreadf1.py, 
ptreadf1.py, and psreadf1.py located in the ReadFiles directory.  These
scripts require a dynamic library (libcmfield1.so).  These python
scripts currently only work in single precision.  The scripts work with
both Python2 and Python3

To compile the dynamic library, execute:

make rfpython

The execute the top level script, type:

python diag1.py

which will call the low level scripts as needed.  It is also possible to
call the low level scripts directly as follows:

python ./ReadFiles/scriptname

where scriptname is either: pcreadf1.py, pvcreadf1.py, pflreadf1.py, 
pfvreadf1.py, ptreadf1.py, or psreadf1.py

To delete the dynamic library, execute:

make rfpyclobber

For more details about compilation, including use of debug graphics, see ReadFiles/README
