Scientific Python Tutorial

An introduction to getting Python up and running, with an emphasis on sharable scientific code.

Prerequisites

A Python environment

Most people manage an environment using pip — the Python package installer — and virtualenv — a tool that creates "virtual environments" to keep project-specific Python environments encapsulated.

For the purposes of this tutorial, we'll use Anaconda, which is a distribution of Python that comes bundled with a number of popular scientific packages.

Click here for instructions on setting up Anaconda.

A text editor

One of the nice things about Python is that it allows you to write short, expressive code. As such, some people feel most productive writing Python programs using a command line text editor such as Vim or Emacs. Or, for those preferring a more typical interface, editors like gedit or Notepad++ have plugins for Python syntax highlighting.

Note for Windows users: Do not use the built-in Notepad program to write or edit code.

There are also a number of options for users that prefer an integrated desktop environment. The most popular IDE for Python is PyCharm, which has a free community edition. For users familiar with Eclipse, PyDev is available as an Eclipse plugin or bundled with LiClipse and Aptana Studio. For users familiar with MATLAB, Spyder, which comes bundled with Anaconda, provides a similar user interface and access to scientific functions.

This tutorial will make use of the IPython Notebook, a browser-based Mathematica-like environment that has become the de facto standard for sharable, interactive, and scientific Python code.

Click here for instructions on using the IPython Notebook.

Some way to share your code

These days most people (myself incldued) prefer to host open source software and information on GitHub. GitHub provides you with a remote Git repository and a web interface that makes it easy to distribute and manage your code.

In addition, nbviewer provides a convenient way to share IPython Notebooks online.

The instructions and IPython Notebooks in this tutorial are available at https://github.com/vr2262/scientific-python-tutorial and http://nbviewer.ipython.org/github/vr2262/scientific-python-tutorial/tree/master/

Getting Started

Scripts

Hello, World!

An executable Python file is simply a text file with the extension .py that contains valid Python code. As such, a basic "hello world" program could look like this (hello.py):

print 'Hello, World!'

You can run this program with the command...

$ python hello.py

which will print to stdout:

Hello, World!

Best Practices

The official Python style guide, known as PEP 8, contains many suggestions about coding and organizational conventions for Python code. Here are some best practices for a Python script (hello_improved.py):

The first line should have a shebang like so:
```
#!/usr/bin/env python
```
The second line should declare the character encoding of the file. You should use UTF-8:
```
# -*- coding: UTF-8 -*-
```
Define units of functionality inside of functions:
```
def main():
    print 'Hello, World!'
```
Any code that should run when the Python file is executed should be inside a special conditional like so:
```
if __name__ == '__main__':
  main()
```

You can now run the script hello_improved.py as before...

$ python hello_improved.py

or you can make the file executable...

$ chmod +x hello_improved.py

and run it as a shell script:

$ ./hello_improved.py

Functions

In Python you define functions with the def keyword and provide a list of arguments. Function execution ends when one of these occurs:

A return or raise statement completes.
An unhandled exception occurs.
The last statement in a function completes without a return. In this case, the output of the function is None.

Example:

def f(x, y):
    z = 2 * x + y
    if z > 5:
        return x
    else:
        raise ValueError('The value of z is too small!')

You can now use the function f anywhere in the file like so:

result = f(5, 10)

Modules

Functions, variables, and classes aren't exactly useful if you can't call them from outside the file in which they're defined. Here is the way the Python module system works (in brief).

Let's say you have a directory structure like

top_module_1.py
top_module_2.py
other_module/
  __init__.py
  utils.py

In the file top_module_1.py, you can access objects from top_module_2.py in the following ways:

import top_module_2
top_module_2.top_function()

import top_module_2 as tm2
tm2.top_function()

from top_module_2 import top_function
top_function()

Because the other_module directory contains an __init__.py file, the Python interpreter knows to look there. You can access objects from the files in the other_module directory like so:

import other_module.utils
other_module.utils.other_function()

import other_module.utils as u
u.other_function()

from other_module.utils import other_function
other_function()

The IPython Notebook

Working IPython notebook examples are in the ipython-notebooks directory.