#acl AdminGroup:read,write,delete,revert  EditorGroup:read,write PythonGroup:read,write All:read
#format wiki
#language en
#pragma section-numbers off

= Python Quick Start =

== Why Python? ==

 * [[http://journals.ametsoc.org/doi/full/10.1175/BAMS-D-12-00148.1|Why Python Is the Next Wave in Earth Sciences Computing]]
 

== Starting the IPython shell as a Notebook ==

{{{
# On the ZMAW system you have to select the newest version with notebooks available
module load python/2.7-ve3

# Start the notebook server in the background
ipython notebook &
}}}

{{{
# The notebook server provides some information about where to find the dashboard

[NotebookApp] Serving notebooks from /home/zmaw/u242023/sync/python/notebooks
[NotebookApp] The IPython Notebook is running at: http://127.0.0.1:8888/
}}}
The dashboard is the central place to collect your scripts (notebooks). Different ports (here :8888) are used if there are additional notebook servers running on the same machine.

You should use firefox to interact with the notebook server. Make sure the Java script is enable when you want to use other browsers.


 * [[http://code.google.com/p/pythonxy/|Try this at home and download Python(x,y)]] 

== Starting the IPython shell ==

{{{
module load python/2.7-ve2

ipython --pylab
}}}
loads matplotlib module and enables interactive plotting

{{{module load}}} is a ZMAW specific environment setting! Version 2.7-ve2 is needed for the notebook version (see below).


Quit with CTRL-D

Getting help
{{{
help()
help modules
}}}
list available modules

'''Features of IPython''':

 * Command history (up, down)
 * Word completion by typing TAB
 * System commands through magic functions cd, ls, env, pwd
 * Access to Unix shell by prefix !, e.g. {{{!ls -s | sort -g}}}
 * Debugging and profiling
 * Program control: {{{run}}}
 * Print interactive variables {{{who, whos}}}




== Are you a Matlab user? ==

The exercise is to plot a sine wave:

Matlab/Octave:
{{{
>> x=linspace(0,2*pi,100)
>> y=sin(x)
>> plot(x,y)
}}}

Python
{{{
In [1]: x=linspace(0,2*pi,100)
In [2]: y=sin(x)
In [3]: plot(x,y)
}}}

So, it works pretty much the same way! 

Of course there are some [[http://www.scipy.org/NumPy_for_Matlab_Users| differences]] but many similarities. 


== Unix basics ==

The ampersand {{{&}}} at the end of a line starts a process in the background. You can get the process in the foreground by typing {{{fg}}}. You can stop a process in the foreground by pressing Control-C.

Within the IPython shell you can use the exclamation mark ! to spawn unix commands. E.g.

{{{
# List directory content
!ls

# Make new directory
!mkdir new_name

# Change to directory
!cd new_name

# Change to an upper level
!cd ..

# Move or rename file or directory
!mv filename_old filename_new
}}}





== Python modules ==

There a several modules which are already included in the standard Python distribution:

 * http://docs.python.org/modindex.html

Other modules for scientific computing have to be installed separately, e.g. Numpy, Scipy, Pylab, IPython. 

Some distributions including precompiled modules are available, e.g.

 * http://www.pythonxy.com/ Python(x,y) is a scientific python distribution with many modules included
 * http://www.enthought.com/products/epd.php

It is important to know where to find the functions that you need. We will go through some useful examples.

=== Numpy ===

Numpy is the core library for multidimensional array objects (ndarray) and linear algebra. Most other scientific modules use the numpy array object. Numpy arrays and standard Python sequences have important differences:

 * Numpy arrays have a fixed size at creation, unlike Python lists
 * Numpy arrays facilitate mathematical operations on large numbers of data efficiently

The [[http://docs.scipy.org/doc/numpy/user/|User's guide]] [[http://docs.scipy.org/doc/numpy/numpy-user.pdf|PDF]] provides a good introduction. 

=== Scipy ===

The Scipy module is built on Numpy and offers a collection of mathematical algorithms such as

 * Clustering algorithms
 * Fast Fourier Transform routines
 * Integration and ordinary differential equation solvers
 * Interpolation and smoothing splines
 * Linear algebra
 * Maximum entropy methods
 * N-dimensional image processing and signal processing
 * Optimization and root-finding routines
 * Statistical distributions and functions

Furthermore it includes very handy routines for [[http://docs.scipy.org/doc/scipy/reference/tutorial/io.html|data input and output]] of binary and ASCII-tables, Matlab and Netcdf data files

=== Pylab ===

[[http://matplotlib.sourceforge.net/|Pylab (aka Matplotlib)]] uses Numpy and Scipy and offers high-level functions that are similar in the name and syntax to those offered by Matlab. Matplotlib is the name of the core library and pylab provides the Matlab similarity. Pylab produces figures of great quality suitable for publications. 

Making plots is easy. Start reading the [[http://matplotlib.sourceforge.net/contents.html|User's guide]]. For a specific problem look at the [[http://matplotlib.sourceforge.net/gallery.html|Gallery]] for a similar plot you would like to have and learn from the source code.

=== IPython ===

[[http://ipython.scipy.org/|IPython]] is an environment for interactive and exploratory computing. Useful features are TAB-completion, magic commands, e.g. {{{%run, %whos}}}, input cache and many more convenient functions that are not available in the standard Python shell. 


=== Importing the scientific environment ===


The statement
{{{
from pylab import *
}}}
imports the most important functions/objects for numerical computation and plotting. When using the interactive IPyhon shell this import is already done with
{{{
ipython --pylab
}}}


For more complex applications it is useful but not necessary to follow the conventions that the community has adopted:
{{{#!python
import numpy as np
import scipy as sp
import matplotlib as mpl
import matplotlib.pyplot as plt
}}}

= Arrays =

Numpy provides a multidimensional '''array''' data type. An array can hold arbitrary Python objects but usually they are used for N-dimensional numeric data types. 

== Array creation ==

 * {{{empty((d1,d2),dtype)}}} returns uninitialized array of shape d1,d2. 
 * {{{zeros((d1,d2),dtype)}}} returns array of shape d1,d2 filled with zeros
 * {{{ones((d1,d2),dtype)}}} returns array of shape d1,d2 filled with ones
 * {{{array(object,dtype)}}} returns an array from an object, e.g. a list
 * {{{dtype}}} fundamental C data type e.g. uint8, int16, int64, float32, float64

Arrays can also be created from special functions, e.g. random

 * {{{randn((d1,d2,..,dn)}}} returns Gaussian random numbers in an array of shape (d0, d1, ..., dn).
 * {{{arange([start,] stop[, step,])}}} returns evenly spaced values within a given interval.


== Array indexing ==

 * {{{A[y,x]}}} returns (y,x) element of the array
 * {{{A[:,x]}}} returns all elements of the y-dimension at x
 * {{{A[y1:y2,x]}}} 
 * {{{A[:,:]}}} returns a copy of two dimensional array A 
 * {{{A[:,:,0]}}} returns the first sub-image of a 3-dimensional array

  
 
= Example and exercise =

Write two programs, a test and a plotting program. The test program shall create a simulated dataset and the plotting routine shall read and display the data on the screen.

We start with a simple linear relation of two variables x and y. The ''measurement'' y shall be influenced by noise with a Gaussian distribution. 


== Generate test data ==

We first would like to generate x including 11 numbers in the intervall [-5,5]
{{{
x=linspace(-5,5,11)
}}}

The variable y depends on x and includes the random noise
{{{
y=x+randn(x.size)
}}}

We write both variables in a file 
{{{
save('data.txt',(x,y))
}}}

Now we combine this in a script. First we open an editor (xemacs, nedit, geany, vi or whatever you like) from the Unix shell 
{{{
nedit generate_test_data.py &
}}}
Create a new file, copy and paste the sourcode, and save (Ctrl-S).

{{{
#!python
from pylab import *

x=linspace(-5,5,11)
y=x+randn(x.size)
savetxt('data.txt',(x,y))
print('Finished!')
}}}

Now you can run the script from IPython 
{{{
In [7]: run generate_test_data.py
Finished!
}}}

Have a look at the variables (objects): 
{{{
In [3]: whos
Variable   Type       Data/Info
-------------------------------
x          ndarray    11: 11 elems, type `float64`, 88 bytes
y          ndarray    11: 11 elems, type `float64`, 88 bytes

In [5]: x
Out[5]: array([-5., -4., -3., -2., -1.,  0.,  1.,  2.,  3.,  4.,  5.])

In [6]: y
Out[6]: 
array([-5.0387728 , -4.28591892, -3.30766546, -1.65761351, -0.19178245,
       -1.52643416,  0.52628016,  0.74130426,  2.99303495,  4.91713939,
        5.13835735])
}}}

== Plot test data ==

The following code can be used as a template
{{{
#!python
from pylab import *

x,y=loadtxt('data.txt')

figure() # Opens a new window for plotting
plot(x,y,'ko') # Plots the data
show() # Displays the result on the screen
savefig('plot.pdf') # Saves the plot on disc
}}}

=== Exercise ===

 * Add a line of identity (y=x) (solid line style)
 * Add a linear regression line with dashed line style
 * Add a legend

Hints: 

 * Look up help(plot) for style options
 * {{{slope,offset=polyfit(x,y,1)}}} can be used for the linear regression
 * Use plot labels and legend(), e.g. plot(x,y,'ko',label='Simulated data')


== Pure Python essentials ==

[[/Python basics|Python basic data types]]

=== Loop ===
{{{
#!python
for i in range(3):
    print i
}}}

== Symbolic math ==

Use isympy or import sympy to obtain a computer algebra system

{{{
isympy 
IPython console for SymPy 0.7.1 (Python 2.7.0-64-bit) (ground types: python)

These commands were executed:
>>> from __future__ import division
>>> from sympy import *
>>> x, y, z, t = symbols('x y z t')
>>> k, m, n = symbols('k m n', integer=True)
>>> f, g, h = symbols('f g h', cls=Function)

Documentation can be found at http://www.sympy.org
}}}

Derivatives
{{{
In [1]: f=sin(x)

In [2]: diff(f,x)
Out[2]: cos(x)
}}}

Series expansion
{{{
In [3]: f.series()
Out[3]: 
     3     5          
    x     x           
x - ── + ─── + O(x**6)
    6    120          
}}}

Simplification
{{{
In [4]: g=sin(x)**2+cos(x)**2

In [5]: simplify(g)
Out[5]: 1
}}}

Integration
{{{
In [7]: F=sin(x)
In [8]: f=diff(F,x)
In [9]: f.integrate()
Out[9]: sin(x)
}}}

Calculus
{{{
In [12]: Rational(1,3)+Rational(1,4)
Out[12]: 7/12
}}}

== Documentation and tutorials ==

 * [[https://wiki.zmaw.de/lehre/PythonCourse|Python at KlimaCampus]]
 * [[http://docs.python.org/2/tutorial/|Python tutorial]] 
 * [[http://matplotlib.org/|Matplotlib/pylab]] for interactive plotting
 * [[http://docs.sympy.org/dev/tutorial/tutorial.en.html#first-steps-with-sympy|SymPy for symbolic mathematics]]