#!/usr/bin/env python
# coding: utf-8

# # PySeison - Tutorial 0: First steps into Python and Ipython

# ## 1. Launching Ipython

# From your shell, ***cd*** to your python workspace/folder and type:
$ipython
# This command will launch Ipython with the *pylab* option on. This option will provide an interactive environment, to generate plots.

# ## 2. Importing libraries

# Importing libraries permits to extend python default functionality by calling exterior code packages. There are several ways to [import libraries in python](http://effbot.org/zone/import-confusion.htm) with different implications. In this tutorial, two different *import* statements will be use.
# 
# Let us import a very useful library, *numpy*. [*numpy*](http://www.numpy.org/) has very similar capability to *matlab* and is therefore widely use in the scientific community.

# In[1]:


import numpy as np


# Here the entire package has been imported and renamed *np*. This format of *import* format is good-practise since it allows to keep track of the package and their attached functions and avoid confusions. for example:

# In[2]:


np.round


# is different from:

# In[3]:


round


# ## 3. Ipython useful shortcuts

# Here is a non-exhaustive list of useful shortcuts available in Ipython:

# - **Tab:** *Tab* completion, especially for attributes, is a convenient way to explore the structure of any object you’re dealing with. Simply type ***object_name.Tab*** to view the object’s attributes (see the [readline section](http://ipython.org/ipython-doc/2/interactive/reference.html#readline) for more). Besides Python objects and keywords, tab completion also works on file and directory names.
# 
# - **Up & down arrows:** IPython stores both the commands you enter, and the results it produces. You can easily go through previous commands with the up- and down-arrow keys, or access your history in more sophisticated ways. One can also use up- and down-arrow keys for auto-completion purposes based on one's command history.
# 
# - **?:** *?* permits a quick access to the documentation of any object or function. Typing ***object_name?*** will unravel the documentation related to the object. Sometimes, one has to type ***q*** to quit the documentation.

# ## 4. Numpy vs. Matlab

# Despite their capability similitudes, there are few major differences between *numpy* and *matlab*. Here follows probably the most important ones:
# - ***[ ] vs. ( ):*** if M is a matrix, i th and j th element of M would be respectively called **M[i,j]** in *numpy* and **M(j,i)** in *matlab*.
# - ***Row-major vs. Column-major:*** as one may has notice the previous point, **the order of row and column indices are inverse** between *python* and *matlab*. Consequently, be extra cautious when translating *matlab* scripts to *python* and similarly when optimisizing double for loops.
# - ***0 to N-1 vs. 1 to N:*** Additionally to the index order, the number attributed to first element of a matrix is different between *python* and *matlab*. **In *matlab*, the number attributed to first element of a matrix is one whereas, in *python* it is zero**, for instance: 

# In[4]:


N = 10
M = np.ones((N)) #define a 1D array of N elements
print "Shape of M: ", M.shape
print "First element= ", M[0]
print "Last element= ", M[9]


# - ***Indentation: *** Python uses whitespace indentation, rather than curly braces or keywords, to delimit blocks; this feature is also termed the off-side rule. An increase in indentation comes after certain statements; a decrease in indentation signifies the end of the current block...this features will be illustrated later on with exercises.

# Fortunately, *numpy* and *matlab* have more similitudes than differences, so much that [*matlab* users](http://mathesaurus.sourceforge.net/matlab-numpy.html) will rapidly make their heads around *numpy* 

# ## 5. PEP convetions

# PEP stands for Python Enhancement Proposals. They are Best-practises type documents for Python programming. It is recommended to follow as much as possible PEP 20, PEP 8 and PEP 257 (i.e.http://legacy.python.org/dev/peps/) 
#