Read Me

PLASMAKIN
=========
PLASMAKIN is a software package to handle physical and chemical data used in 
plasma physics modeling and to compute:
    - gas-phase and surface kinetics;
    - electron kinetics;
    - several diagnostics: power losses, emission spectrum, etc.
PLASMAKIN is not a model for any particular type of discharge. The building of
such a model is your responsibility. However PLASMAKIN helps taking care of all
the data management related to species, reactions and computation of a lot of 
other information that may be needed to solve your model equations.
In a simple image, if your problem is studied through a fluid model, including
the continuity and momentum transfer equations for the species, and, eventually,
an energy conservation equation, PLASMAKIN takes care of the right-side terms 
(and also some of the left-side terms) while you take care of the correctness 
of the model and the algorithm to solve it.


License
=======
PLASMAKIN is released under a GNU GPL License.
This means that you have access to the source code and can modify it for your 
own purposes.
However as with any other scientific work, if you use the package or any of its
components in your work, it is expected that you give due acknowledgement of 
its use. One way of doing is to use the following reference:

N. R. Pinhão, "PLASMAKIN: A library to evaluate the chemical kinetics in gases",
(2001-2008), http://plasmakin.sourceforge.net

For the detailed licence terms, see LICENSE.

We would also appreciate if you could spend a few minutes of your time to drop 
us a short note telling us how and where are you using it, your impressions, 
critics or suggestions of improvement. Off course any contribution - in coding,
debugging, documentation or translation - is always welcomed.


Third Party Software
====================
The standard PLASMAKIN installation depends on third party software: The Python
interpreter and the SQLite database engine.
However PLASMAKIN distribution does not include these tools and it is up to you
to obtain and install them. This should not be a problem as both are included 
in most Linux distributions and on Mac OS X. Versions for other operating 
systems are easily obtainable from, respectively:
http://www.python.org and http://www.sqlite.org.

The Fortran support to SQLite included in the directory sqlite, was developed
by Arjen Markus and Michael Baudin (http://fortran.sqlite.org) and to compile
it you need the SQLite header file sqlite.h (see link above).
The plasmakin.db and tests.db (used only with make check) databases are no
longer included in the distribution.
Instead of these databases the package includes two sql command files to create
the databases on installation. However you need the sqlite3 program to generate
the databases. If you have it the make (or make check) instructions take care
of everything.

To visualize and simple editing of sqlite databases I find very useful a sqlite
database browser: sqlitebrowser. It can be found in most Linux distributions 
and on http://sqlitebrowser.sourceforge.net.

The support to any of these tools can be disabled as explained bellow.


Installation
============
For installation in MS Windows systems see bellow. Otherwise, for UNIX/Linux
and Mac OS X systems the installation is very simple and just requires three 
instructions:

`./configure'
`make'
`make install' # (as root)

Detailed instructions can be found on INSTALL.

Installation options
--------------------
PLASMAKIN supports several installation options with `./configure'. The full 
list of installation options can be seen with `./configure --help' but those 
specific to PLASMAKIN are the following:

`--enable-sqlite3'
     Enables sqlite3 database support This option is enable by default 
     (equivalent to `--enable-sqlite3=true'). If you wish to disable it use 
     `--disable-sqlite3' or `--enable-sqlite3=false'.

`--enable-python'
     Enables Python scripting support. This option is enable by default 
     (equivalent to `--enable-python=true'). If you wish to disable it use 
     `--disable-python' or `--enable-python=false'.

`--enable-examples'
     Includes and build example programs. This option is disabled by default 
     (equivalent to `--enable-examples=false'). If you wish to enable it use 
     `--enable-examples=true'.


Note: Configuring the dynamic linker
====================================
If PLASMAKIN libraries are built as shared libraries, the dynamic linker (ld 
in Linux/Unix and Mac OS X systems) needs to know about that. This is usually 
done adding the line '/usr/local/lib/plasmakin' (or the path to where the 
libraries can be found) to the file '/etc/ld.so.conf' and runing ldconfig to 
update the necessary links and cache information. In alternative, if you system 
uses a separate directory (/etc/ld.so.conf.d/) to split the path information on
individual libraries, you need to write on that directory a file called 
'plasmakin.conf' with the above line and run ldconfig as before.


Installation on MS Windows operating systems
============================================
You have two options:
a) Install a compatible UNIX shell, the necessary GNU programs and follow the
installation instructions above, or
b) Build your own Makefiles from the supplied configure.ac and Makefile.am...

Although not exactly easy the 1st alternative if probably faster. As a UNIX shell
I suggest MinGW (http://www.mingw.org/).

Checking your installation
=========================
After installation you can run a series of tests to check if everything is well
set in your system with the instruction:

`make check'


Cleaning your installation
=========================
After compilation, installation and runing the tests, you may wish to clean the
unnecessary files. Just run:

`make clean' or `make distclean'


Documentation
=============
The present manual is already old and outdated. The update of the manual is on
the task list for the following months (unfortunately with a large uncertainty 
on when I will be able to do that...). Meanwhile the doc directory includes the
old version and two articles that have been published on the initial version 
and on pypk respectively.
Other sources of information are the test programs on the test and examples 
directories and the code itself.


Support
=======
If you have difficulties with installing or using PLASMAKIN please be aware that
PLASMAKIN is a non-profit project and most of it has been develloped on my free
time. If you believe you have found a bug I would appreciate to know about it,
preferably with a simple test case. Please report on the bugs tracker for this
project on sourceforge or email me. However I can not promise to dedicate time
to it. However I would gladly give all the advice to help you solving it.
I also advice users to subscribe to the PLASMAKIN mailing list:
plasmakin-users@lists.sourceforge.net (just go to the sourceforge page to 
subscribe) and to check the bugs list and the news on:
http://sourceforge.net/projects/plasmakin.