Installation¶
Requirements¶
The only requirements are
- Python 2.7. (Python 3 support is in the works)
- numpy (1.6 or later)
Because pyqg is a pseudo-spectral code, it realies heavily on fast-Fourier transforms (FFTs), which are the main performance bottlneck. For this reason, we try to use fftw (a fast, multithreaded, open source C library) and pyfftw (a python wrapper around fftw). These packages are optional, but they are strongly recommended for anyone doing high-resolution, numerically demanding simulations.
If pyqg can’t import pyfftw at compile time, it will fall back on numpy‘s fft routines.
Instructions¶
In our opinion, the best way to get python and numpy is to use a distribution such as Anaconda (recommended) or Canopy. These provide robust package management and come with many other useful packages for scientific computing. The pyqg developers are mostly using anaconda.
Note
If you don’t want to use pyfftw and are content with numpy’s slower performance, you can skip ahead to Installing pyqg.
Installing fftw and pyfftw can be slightly painful. Hopefully the instructions below are sufficient. If not, please send feedback.
Installing fftw and pyfftw¶
Once you have installed pyfftw via one of these paths, you can proceed to Installing pyqg.
The easy way: installing with conda¶
If you are using Anaconda, we have discovered that you can easily install
pyffw using the conda
command. Although pyfftw is not part of the main
Anaconda distribution, it is
distributed as a conda pacakge through several user channels.
There is a useful blog post describing how the pyfftw conda package was created. There are currently 13 pyfftw user packages hosted on anaconda.org. Each has different dependencies and platform support (e.g. linux, windows, mac.) The mforbes channel version was selected for this documentation because its pyfftw package is compatible with the latest version of numpy (1.9.2) and both linux and mac platforms. We don’t know who mforbes is, but we are greatful to him/her.
To install pyfftw from the mforbes channel, open a terminal and run the command
$ conda install -c mforbes pyfftw
If this doesn’t work for you, or if it asks you to upgrade / downgrade more of
your core pacakges (e.g. numpy) than you would like, you can easily try
replacing mforbes
with one of the other channels.
The hard way: installing from source¶
This is the most difficult step for new users. You will probably have to build FFTW3 from source. However, if you are using Ubuntu linux, you can save yourself some trouble by installing fftw using the apt package manager
$ sudo apt-get install libfftw3-dev libfftw3-doc
Otherwise you have to build FFTW3 from source. Your main resource for the FFTW homepage. Below we summarize the steps
First download the source code.
$ wget http://www.fftw.org/fftw-3.3.4.tar.gz
$ tar -xvzf fftw-3.3.4.tar.gz
$ cd fftw-3.3.4
Then run the configure command
$ ./configure --enable-threads --enable-shared
Note
If you don’t have root privileges on your computer (e.g. on a shared
cluster) the best approach is to ask your system administrator to install
FFTW3 for you. If that doesn’t work, you will have to install the FFTW3
libraries into a location in your home directory (e.g. $HOME/fftw
) and
add the flag --prefix=$HOME/fftw
to the configure command above.
Then build the software
$ make
Then install the software
$ sudo make install
This will install the FFTW3 libraries into you system’s library directory.
If you don’t have root privileges (see note above), remove the sudo
. This
will install the libraries into the prefix
location you specified.
You are not done installing FFTW yet. pyfftw requires special versions of the FFTW library specialized to different data types (32-bit floats and double-long floars). You need to-configure and re-build FFTW two more times with extra flags.
$ ./configure --enable-threads --enable-shared --enable-float
$ make
$ sudo make install
$ ./configure --enable-threads --enable-shared --enable-long-double
$ make
$ sudo make install
At this point, you FFTW installation is complete. We now move on to pyfftw.
pyfftw is a python wrapper around the FFTW libraries. The easiest way to
install it is using pip
:
$ pip install pyfftw
or if you don’t have root privileges
$ pip install pyfftw --user
If this fails for some reason, you can manually download and install it according to the instructions on github. First clone the repository:
$ git clone https://github.com/hgomersall/pyFFTW.git
Then install it
$ cd pyFFTW
$ python setup.py install
or
$ python setup.py install --user
if you don’t have root privileges. If you installed FFTW in a non-standard location (e.g. $HOME/fftw), you might have to do something tricky at this point to make sure pyfftw can find FFTW. (I figured this out once, but I can’t remember how.)
Installing pyqg¶
With pyfftw installed, you can now install pyqg. The easiest way is with pip:
$ pip install pyqg
You can also clone the pyqg git repository to use the latest development version.
$ git clone https://github.com/pyqg/pyqg.git
Then install pyqg on your system:
$ python setup.py install [--user]
(The --user
flag is optional–use it if you don’t have root privileges.)
If you want to make changes in the code, set up the development mode:
$ python setup.py develop
pyqg is a work in progress, and we really encourage users to contribute to its Development