A first glance
==============
Introduction
------------
The *WaveBlocks* project is a collection of reusable software components
providing many of the objects used in the study of semi-classical wave-packets.
Currently it's all about the time-dependent Schrödinger equation and the time
evolution of initial states.
One of the main goals is to provide a set of building blocks - hence the project's
name - that are well tested and reliable. The included features range from
very simple mathematical operations like specialized quadrature rules to basic
data structures for semi-classical wave-packets to more high-level simulation
algorithms and some non-standard plotting functions. Of course there are also
routines included for saving, managing and evaluating simulation results inflexible
manner. All of these components are put together in an easy to use and easy to
extend framework.
The whole project is written in the `Python` programming language and a strong
emphasis is put on readable code and clean software design. Speed and efficiency
are, however, not the main concern for the moment.
Download
--------
The *WaveBlocks* project has its home at GitHub:
https://github.com/WaveBlocks
where there are several closely related ``git`` repositories. The latest version
of this project can be found in the ``git`` repository:
https://github.com/WaveBlocks/WaveBlocksND
Check out the ``master`` branch for the main development version or one of the
tags for stable and released versions. There are also branches used for developing
special features before they are ready to get merged into the ``master`` branch.
Dependencies
------------
The ``WaveBlocksND`` software depends on some more or less well known `Python` packages,
that are not installed by default. On any recent Linux distribution (for example `Debian`)
you can use the package manager to download and install all the dependencies.
The simulation code is compatible with `Python 3.4` and above. Hence, make sure to
get the correct version of all dependencies. All packages can also be installed
via the ``pip`` `tool `_ from
the `Python Package Index `_.
The necessary dependencies are listed here together with a brief statement of why we need the package.
* ``numpy``, available from https://www.numpy.org
Numpy provides fast multidimensional arrays.
* ``scipy``, available from https://www.scipy.org
Scipy interfaces to fast numerical subroutines (BLAS, LAPACK, FFTW).
* ``sympy``, available from https://sympy.org
Sympy gives rise to symbolic calculation.
* ``matplotlib``, available from http://matplotlib.org
Matplotlib is used for two-dimensional plotting.
* ``h5py``, available from https://h5py.org
H5py is the interface to the Hierarchical Data Format `hdf`.
* ``mayavi2``, available from https://github.com/enthought/mayavi
Mayavi2 is used for three-dimensional plotting.
The ``mayavi2`` dependency is weak in the sense that the whole ``WaveBlocksND`` code
runs fine without it and only the 3-dimensional plotting functions are not available.
Installation
------------
In the following section be sure not to mix up the name *WaveBlocks* that
stands for the whole project and the name ``WaveBlocksND`` which is the
name of the `Python` package.
By using the `Python` ``virtualenv`` `utility `_,
we can easily create a completely isolated `Python` environments. Any `Python`
package can then be installed locally within such an environment without affecting
the outer world.
For Users
~~~~~~~~~
First, we create a new `virtualenv` called ``waveblocks`` which we allow access to
all the `Python` packages that are already installed on the system:
::
virtualenv -p /usr/bin/python3.4 --system-site-packages waveblocks
This assumes that the dependencies are installed globally on the system.
If we want a truly isolated environment, we can omit the switch ``--system-site-packages``.
This will cause all packages to be built and installed locally to this `virtualenv`.
.. note:: Make sure you adapt the path to the `Python` interpreter, in this
example ``/usr/bin/python3.4``, to fit your own system.
Next, we switch into the directory and activate the `virtualenv`:
::
cd waveblocks
source ./bin/activate
Finally, we can install the ``WaveBlocksND`` software directly from the `git` repository
by running:
::
pip install git+https://github.com/WaveBlocks/WaveBlocksND.git#egg=WaveBlocksND
That is all we have to do.
.. note:: If you want to install another branch instead of ``master`` from the `git` repository,
use the ``@`` syntax of `pip`. For example, to install a branch named ``newfeature``
use the command::
pip install git+https://github.com/WaveBlocks/WaveBlocksND.git@newfeature#egg=WaveBlocksND
.. note:: Before using the software, **always** go back to the ``waveblocks`` directory
and run ``source ./bin/activate`` there to active the ``virtualenv``.
Note that this action is **local** to the current shell instance.
For Developers
~~~~~~~~~~~~~~
If you plan to modify the source code, first clone the `git` repository:
::
git clone https://github.com/WaveBlocks/WaveBlocksND.git ~/waveblockssource
The clone is put into the directory ``~/waveblockssource``. The directory listing should now look like:
::
LICENSE MANIFEST.in README.md WaveBlocksND doc examples scripts setup.py
Next, you can create and activate the `virtualenbv` like above. The run the following command
to install the software within the `virtualenv`:
::
pip install -e ~/waveblockssource
Note the ``-e`` switch, which connects the source code in ``~/waveblockssource`` with the
installation inside the `virtualenv` at ``~/waveblocks``.
Software Overview
-----------------
The *WaveBlocks* package consists of two parts. On one hand there is a `Python` library
and on the other hand there are a bunch of scripts that use this library to implement common
computations.
The Library
~~~~~~~~~~~
The library is called ``WaveBlocksND`` and can be imported in `Python` by the usual procedure:
::
import WaveBlocksND
this will bring a large number of objects into scope:
::
dir(WaveBlocksND)
['AbstractGrid', 'BasisShape', 'BasisTransformation', 'BasisTransformationHAWP', 'BasisTransformationWF', ...
For the details, please refer to the class documentation.
The Scripts
~~~~~~~~~~~
The scripts (everything in the ``scripts/`` source directory) perform simulations, data evaluation and plotting.
During installation, these scripts are copied into the ``virtualenv`` local ``bin/`` directory and this location is on
the ``$PATH``. Hence the scripts can be called from anywhere as long as the ``virtualenv`` is activated.
These files are just plain `Python` scripts that import the ``WaveBlocksND`` `Python` module. It is `not` necessary
to call the scripts via a `Python` interpreter as all have a proper shebang line (``#!/usr/bin/env python``).
The scripts all support online help when called with the ``--help`` switch.
Supported platforms
-------------------
The ``WaveBlocksND`` code might run on `Windows` and `OS X` and the various
`BSD` variants too, provided that the required `Python` dependencies are installed.
However, this has never been tested. The primary development platform is `GNU/Linux`
and in particular the `Debian` distribution.