Tim Green / MagresPython


Installing and updating

The following commands should be entered at the command line, usually with a program called something like Terminal. Incidentally, if you are using OS X, I recommend iTerm2 as a good terminal to work with.


Install Python and necessary packages using your operating system package manager, or get Anaconda. Once you have Python installed, run the following commands in a terminal.

cd ~
git clone https://github.com/tfgg/magres-format.git
cd magres-format
python setup.py install --user

If you have trouble with this, there are more detailed instructions below.

To update to the latest version, cd into the magres-format folder and run

git pull
python setup.py install --user


MagresPython has been tested with Python versions 2.6 and 2.7 and will likely not work with other versions. You should have one of these available on your system; you can test this by running the python command from the command line. For example,

$ python
Python 2.7.4 (default, Sep 26 2013, 03:20:26) 
[GCC 4.7.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.

which gives a Python version of 2.7.4, which is fine.

An easy way to get Python and all of the necessary packages installed is the Anaconda distribution.

If not, you should find out how to get it, preferably by your operating system’s package manager, such as apt on the Debian and Ubuntu flavours of Linux. If you are using a high-performance computing (HPC) facility, such as ARCHER, it may be available as a module that you can load.

MagresPython uses the numpy Python module for some linear algebra computations. You may also find the matplotlib and scipy modules helpful for following the tutorials and doing your own processing.

You can test if you have these modules by opening a python shell and executing the import commands, giving output similar to the following if successful.

$ python
Python 2.7.4 (default, Sep 26 2013, 03:20:26) 
[GCC 4.7.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import numpy
>>> import matplotlib
>>> import scipy

Only numpy is essential. If you are missing any modules, you can download these using the pip Python package manager, your operating system package manager, or by loading modules on your HPC.

You can get the latest version of the library using the git tool. This may not be installed by default on your system. In some appropriate directory run the following commands

git clone https://github.com/tfgg/magres-format.git
cd magres-format

and then follow the rest of the installation process. This is the recommended way to get MagresPython as it will allow you to easily get future updates by running the git pull command in the magres-format directory.

Downloading the zip

If the git tool isn’t available, you can download using a command such as curl, which should be available on most systems. In some appropriate directory run the following commands

curl -L "https://github.com/tfgg/magres-format/archive/master.zip" -o "master.zip"

and then extract the zip file using the unzip command and cd into the extracted directory

unzip master.zip
cd magres-format-master


Installing the library will give you access to the code and scripts from anywhere on your system. You will be able to import the magres module into your Python code and run scripts such as extract-ms.py.

You can now install the library either system wide, which may need superuser privileges, or locally in your user directory, which may require modifying your PATH environment variable. You could also install it in a virtual environment, which will isolate it from the rest of your Python system, reducing the chance of dependency clashes and generally keeping things clean.

System wide

To install system wide, in the directory that you downloaded and extracted the library to, run the following command

sudo python setup.py install

you may need to enter a password. If this fails, you may not have superuser privileges, in which case you will have to install locally.

Locally for your user

To install locally in your user directory, run the following command

python setup.py install --user

In a virtual environment

First, get virtualenv and ensure that it is installed. Then, create a virtual environment directory inside your magres-format directory.

cd magres-python
virtualenv venv

Activate the virtual environment. You will need to do this every time you want to use MagresPython.

source venv/bin/activate

Now, install all the requirements and magres-python.

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

You should now have a clean, isolated setup of MagresPython and its dependencies.

Setting up scripts and PATH

You may be prompted to add your user bin directory to your PATH environment variable, or you may find that scripts aren’t executing properly. How you fix this depends on what shell you are using. To find out what shell you are using, run the following command

echo $SHELL

If the output is something like /bin/bash, then you are running the bash shell. If it is something like /bin/tcsh then you are running the tcsh shell. There are a number of other shells which I won’t cover here.

If you are using bash, add the following line to your ~/.bashrc.

export PATH=$HOME/.local/bin:$PATH

If you are using tcsh, add the following line to your ~/.tcshrc.

setenv PATH $HOME/.local/bin:$PATH

Once you have done this you should restart your terminal session.

Checking the installation

To check that the library is correctly installed you can try importing the magres module and running a script. To check that the module is correctly imported, open a Python shell and execute import magres

$ python
Python 2.7.4 (default, Sep 26 2013, 03:20:26) 
[GCC 4.7.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import magres

which should run without error.

To check a script, navigate to a directory, preferably with a calculation in it, and run the following comand in the terminal

extract-ms.py --help

which should output the help information for the extract-ms.py script.