Installation and getting started¶

Quick installation¶

If you are reasonably experienced with installing Python packages, already have a C++ compiler setup on your machine, and are not immediately interested in running PySPH on multiple CPUs (using MPI), then installing PySPH is simple. Simply running pip like so:

$ pip install PySPH

should do the trick. You may do this in a virtualenv if you chose to. The important examples are packaged with the sources, you should be able to run those immediately. If you wish to download the sources and explore them, you can download the sources either using the tarball/ZIP or from git, see Downloading PySPH.

The above will install the latest released version of PySPH, you can install the development version using:

$ pip install git+https://bitbucket.org/pysph/pysph.git#egg=PySPH

If you wish to track the development of the package, clone the repository (as described in Downloading PySPH and do the following:

$ pip install -r requirements.txt
$ python setup.py develop

The following instructions are more detailed and also show how optional dependencies can be installed. Instructions on how to set things up on Windows is also available below.

Dependencies¶

$ ./build_zoltan.sh INSTALL_PREFIX

$ export ZOLTAN=$INSTALL_PREFIX

$ export ZOLTAN_INCLUDE=$INSTALL_PREFIX/include
$ export ZOLTAN_LIBRARY=$INSTALL_PREFIX/lib

Installing the dependencies on GNU/Linux¶

GNU/Linux is probably the easiest platform to install PySPH. On Ubuntu one may install the dependencies using:

$ sudo apt-get install build-essential python-dev python-numpy \
    python-mako cython python-nose mayavi2 python-qt4 python-virtualenv

OpenMP is typically available but if it is not, it can be installed with:

$ sudo apt-get install libgomp1

If you need parallel support:

$ sudo apt-get install libopenmpi-dev python-mpi4py
$ ./build_zoltan.sh ~/zoltan # Replace ~/zoltan with what you want
$ export ZOLTAN=~/zoltan

On Linux it is probably best to install PySPH into its own virtual environment. This will allow you to install PySPH as a user without any superuser priviledges. See the section below on Using a virtualenv for PySPH. In short do the following:

$ virtualenv --system-site-packages pysph_env
$ source pysph_env/bin/activate
$ pip install cython --upgrade # if you have an old version.

You should be set now and should skip to Downloading PySPH and Building and Installing PySPH.

If you are using Enthought Canopy or Anaconda the instructions in the section Installing the dependencies on Mac OS X will be useful as the instructions are similar.

Installing the dependencies on Mac OS X¶

On OS X, your best bet is to install Enthought Canopy or Anaconda or some other Python distribution. Ensure that you have gcc or clang installed by installing XCode. See this if you installed XCode but can’t find clang or gcc.

$ sudo brew install gcc

$ cd /usr/local/include
$ sudo ln -s ../Cellar/gcc/4.9.2_1/lib/gcc/4.9/gcc/x86_64-apple-darwin12.6.0/4.9.2/include/omp.h .

$ export CC=gcc-4.9
$ export CXX=g++-4.9

$ pip install cython mako

$ enpkg mayavi

$ conda install cython mayavi
$ pip install mako

$ sudo brew install open-mpi

$ cd /tmp
$ tar xvzf ~/Downloads/mpi4py-1.3.1.tar.gz
$ cd mpi4py-1.3.1
$ export MACOSX_DEPLOYMENT_TARGET=10.7
$ export SDKROOT=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.7.sdk/
$ python setup.py install

$ cd pysph
$ ./build_zoltan.sh ~/zoltan # Replace ~/zoltan with what you want
$ export ZOLTAN=~/zoltan

Installing the dependencies on Windows¶

While it should be possible to use mpi4py and Zoltan on Windows, we do not at this point have much experience with this. Feel free to experiment and let us know if you’d like to share your instructions. The following instructions are all without parallel support.

> pip install cython mako

> enpkg mayavi

$ conda install cython mayavi
$ pip install mako

Using a virtualenv for PySPH¶

A virtualenv allows you to create an isolated environment for PySPH and its related packages. This is useful in a variety of situations.

• Your OS does not provide a recent enough Cython version (say you are running Debian stable).
• You do not have root access to install any packages PySPH requires.
• You do not want to mess up your system files and wish to localize any installations inside directories you control.
• You wish to use other packages with conflicting requirements.
• You want PySPH and its related packages to be in an “isolated” environment.

You can either install virtualenv (or ask your system administrator to) or just download the virtualenv.py script and use it (run python virtualenv.py after you download the script).

Create a virtualenv like so:

$ virtualenv --system-site-packages pysph_env

This creates a directory called pysph_env which contains all the relevant files for your virtualenv, this includes any new packages you wish to install into it. You can delete this directory if you don’t want it anymore for some reason. This virtualenv will also “inherit” packages from your system. Hence if your system administrator already installed NumPy it may be imported from your virtual environment and you do not need to install it. This is very useful for large packages like Mayavi, Qt etc.

Once you create a virtualenv you can activate it as follows (on a bash shell):

$ source pysph_env/bin/activate

On Windows you run a bat file as follows:

$ pysph_env/bin/activate

This sets up the PATH to point to your virtualenv’s Python. You may now run any normal Python commands and it will use your virtualenv’s Python. For example you can do the following:

$ virtualenv myenv
$ source myenv/bin/activate
(myenv) $ pip install Cython mako nose
(myenv) $ cd pysph
(myenv) $ python setup.py install

Now PySPH will be installed into myenv. You may deactivate your virtualenv using the deactivate command:

(myenv) $ deactivate
$

On Windows, use myenv\Scripts\activate.bat and myenv\Scripts\deactivate.bat.

If for whatever reason you wish to delete myenv just remove the entire directory:

$ rm -rf myenv

$ python `which ipython`

$ venv --help
$ venv --system-site-packages myenv
$ source myenv/bin/activate

Downloading PySPH¶

One way to install PySPH is to use pip

$ pip install PySPH

This will install PySPH, and you should be able to import it and use the modules with your Python scripts that use PySPH. This will also provide the standard set of PySPH examples. If you want to take a look at the PySPH sources you can get it from git or download a tarball or ZIP as described below.

To get PySPH using git type the following

$ git clone https://bitbucket.org/pysph/pysph.git

If you do not have git or do not wish to bother with it, you can get a ZIP or tarball from the pysph site. You can unzip/untar this and use the sources.

In the instructions, we assume that you have the pysph sources in the directory pysph and are inside the root of this directory. For example:

$ unzip pysph-pysph-*.zip
$ cd pysph-pysph-1ce*

or if you cloned the repository:

$ git clone https://bitbucket.org/pysph/pysph.git
$ cd pysph

Once you have downloaded PySPH you should be ready to build and install it, see Building and Installing PySPH.

Building and Installing PySPH¶

Once you have the dependencies installed you can install PySPH with:

$ pip install PySPH

If you downloaded PySPH using git or used a tarball you can do:

$ python setup.py install

You could also do:

$ python setup.py develop

This is useful if you are tracking the latest version of PySPH via git. With git you can update the sources and rebuild using:

$ git pull
$ python setup.py develop

You should be all set now and should next consider Running the tests.

Running the tests¶

Once you install PySPH you can run the tests using the pysph script that is installed:

$ pysph test

If you see errors while running the tests, you might want more verbose reporting which you can get with:

$ pysph test -v

This should run all the tests that do not take a long while to complete. If this fails, please contact the pysph-users mailing list or send us email.

Once you run the tests, you should see the section on Running the examples.

For more information on what you can do with the pysph script try this:

$ pysph -h

Running the examples¶

You can verify the installation by exploring some examples. The examples are actually installed along with the PySPH library in the pysph.examples package. You can list and choose the examples to run by doing:

$ pysph run

This will list all the available examples and allow you to run any of them. If you wish to run a particular one, like say elliptical_drop, you may do:

$ pysph run elliptical_drop

This can also be run as:

$ pysph run pysph.examples.elliptical_drop

To see the options available, try this:

$ pysph run elliptical_drop -h

You can view the data generated by the simulation (after the simulation is complete or during the simulation) by running pysph view command. To view the simulated data you may do:

$ pysph view elliptical_drop_output

If you have Mayavi installed this should show a UI that looks like:

There are other examples that use the transport velocity formulation:

$ pysph run cavity

This runs the driven cavity problem using the transport velocity formulation of Adami et al. The example also performs post-processing of the results and the cavity_output will contain a few PNG images with these. For example for example the file streamlines.png may look like what is shown below:

If you want to use PySPH for elastic dynamics, you can try some of the examples from Gray et al., Comput. Methods Appl. Mech. Engrg. 190 (2001), 6641-6662:

$ pysph run solid_mech.rings

Which runs the problem of the collision of two elastic rings:

The auto-generated code for the example resides in the directory ~/.pysph/source. A note of caution however, it’s not for the faint hearted.

$ pysph run elliptical_drop --openmp

$ OMP_NUM_THREADS=8 pysph run elliptical_drop --openmp

$ pysph run elliptical_drop --disable-output --openmp

$ python pysph_script.py

$ mpirun -np 4 pysph run dam_break_3d

Organization of the pysph package¶

PySPH is organized into several sub-packages. These are:

• pysph.base: This subpackage defines the pysph.base.particle_array.ParticleArray, pysph.base.carray.CArray (which are used by the particle arrays), the various SPH Kernels, the nearest neighbor particle search (NNPS) code, and the Cython code generation utilities.
• pysph.sph: Contains the various SPH equations, the Integrator module and associated integration steppers, and the code generation for the SPH looping. pysph.sph.wc contains the equations for the weakly compressible formulation. pysph.sph.solid_mech contains the equations for solid mechanics and pysph.sph.misc has miscellaneous equations.
• pysph.solver: Provides the pysph.solver.solver.Solver, the pysph.solver.application.Application and a convenient way to interact with the solver as it is running.
• pysph.parallel: Provides the parallel functionality.
• pysph.tools: Provides some useful tools including the pysph script CLI and also the data viewer which is based on Mayavi.
• pysph.examples: Provides many standard SPH examples. These examples are meant to be extended by users where needed. This is extremely handy to reproduce and compare SPH schemes.