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:

where there are several closely related git repositories. The latest version of this project can be found in the git repository:

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.

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.