Home

Quick Start

Data

Python

Courseware

Lecture Graphics

Problems

Solutions

Bibliography

Python Links

Python Home

python.org

Basic install

Graphics

Learning Python

 

Overview

Python is an interpreted, open-source, object-oriented language. "Interpreted" means you just type a statement or series of statements, and they execute as soon as the statements make up a complete command, without the need to first compile the statements into machine language. In this regard, Python is like Matlab. "Open-source" means that nobody owns it or sells it, and that it is developed and maintained by a large community of dedicated users. Anybody can see how the thing works, and there are no secrets. Open-source means Python costs nothing, and so nobody needs to deal with the hassle and cost of licensing. Python has a very extensive user base, so it's not going away any time soon. All Unix-like operating systems heavily make use of Python, and Google largely runs on Python. One of the virtues of Python is that it is very easy to extend; for high performance, Fortran libraries can easily be turned into Python commands using f2py (distributed with numpy) and c or c++ libraries can easily be turned into Python commands using swig. "Object-oriented" means that Python supports the definition of structures which combine places to store data with functions that operate on the data, making for a very powerful way of building toolkits. Python provides a very gentle and intuitive way of getting used to this software development technique, though the language can also be used perfectly well in the old-fashioned familiar procedural way.

The current version of Python is Python 3, which has been around for several years, but it is not completely backward compatible with Python 2.7 (the last Python 2 release) and some users have stuck with Python 2.7. For most scientific users, the incompatibilities will not be evident (apart from some minor changes in the print statement). Python 3 has become quite stable, and it is suggested that users install that version unless there is a good reason for doing otherwise. All courseware material should work with either version, however.

Although Python is an open-source language which is distributed without charge, as are most of the extensions that scientific users would need, putting together a suitable installation from all the bits and pieces available out on the web can be a bit tricky. Happily, there are two distributions which provide all the basics needed for scientific computation in Python, and which are made available at no cost. Both install easilyl on Mac or Windows using one-click installers, and can be installed easily on Linux systems as well usin the usual Linux distribution tools. Even if your system already has some form of Python installed, it is best to install a fresh version of one of these distributions, so that you can be sure you have what you need, and so that you can customize your Python installation without interfering with the version of Python your operating system may be using to perform some of its tasks. As long as one of these two distributions are distributed at no cost, there is no reason to look elsewhere.

Most users will not need to know anything else on the remainder of this page, or in Basic install or Graphics, and will be able to proceed directly to Learning Python after installing one of the above Python distributions. Learning Python describes the basic ways of interacting with Python, including the command-line python or ipython interpreters and GUI (graphical user interface) integrated development environments like the Canopy app. The additional material below is mostly a legacy from a time when users needed to craft their own installation, but I have preserved it for those few who may still be in that situation. Instructors who wish to set up a server to make Python available to students over the network, as an alternative to students installing Python on their individual computers, should look here.

Readers using Python in connection with Principles of Planetary Climate can then proceed to install the Courseware and start becoming familiar with its use (beginning with the Computational Toolkit exercises in the Chapter 1 Workbook).

 

The remainder of this page contains information that will be of use to some advanced users, or users in special situations:

 

back to top

Where to put add-on modules

One of the great virtues of Python is that it is very easy to extend the basic capability of the language with new commands and functionality. The expansion packages take the form of modules.

A module is really no different than any other Python script. It is simply a Python script that is intended to define a bunch of functions, constants and other objects that are generally useful in a wide range of applications. A module called MyModule.py would be imported into Python using the command

import MyModule

There are other ways to import modules, described under Learning Python.

If you want Python to be able to find your extension modules no matter what directory you are working from, you need to either put the modules in the some place where Python looks by default, or to tell Python where you want it to look. A script which imports a module will always find that module if the module is located in current working directory.

The other place Python looks for modules by default, is the directory site-packages. which is deep down in the directory tree of the directory where Python itself has been installed. (See Basic install for information on where to find the site-packages directory.) Putting things here normally requires system-administrator permission. This is where you would put things that are intended to be available system-wide to all Python users, for example the numpy array package and the graphics package you are using. A user can examine scripts in site-packages, but this is not the place to put scripts that that the user or instructor will want to modify frequently. There is nothing really wrong with putting the courseware modules in the site-packages directory. Putting courseware modules in site-packages also works in Microsoft Windows. Depending on how Python was installed, you might need administrator privileges to install thinks in site-packages. Typically, installation software runs with administrator privileges and puts things in site-packages.

I prefer to keep special-purpose modules in a separate directory in my home directory, though it is possible for other users to import those modules if the directory is made readable by others. You can have as many such directories as you want, and they can be put anywhere where you have read permission. However, you have to somehow tell Python to look in these directories as well as the default places. On Unix-like systems, including Mac OSX, this is handled by setting the PYTHONPATH environment variable. Doing this takes you into fairly geeky territory, described under About Shells, Paths and Environment Variables. Microsoft Windows also has environment variables, and you can set PYTHONPATH using either a dialog box or the set command. Instructions on how to do this are found here (see Section 3.3.1).

Once you set up your PYTHONPATH to find a modules directory (say, MyModules), any script placed in that directory (say, MyScript.py ) can be imported by name, e.g

import MyScript

However, if you put a subdirectory in your modules directory, Python will not be able to find those modules. For example, if MyModules contains a subdirectory called Package, which contains scripts Package/MyScript1.py and Package/MyScript2.py , then import MyScript1 ,etc. won't work. However if the subdirectory contains a special script __init__.py (note double underscores) which tells Python what to import, then an import of the subdirectory name ( import Package , in the example given) will work. Developers who wish to group many scripts into a single directory you can install typically will do this, but you will probably never need to do this yourself.

On Mac OSX or Linux, if you start the Canopy app from a command line using the bash shell (by typing canopy), then Python running under the Canopy app will inherit the PYTHONPATH you set in the shell. However, on Mac OS X, if you start the Canopy app by clicking on its icon, the environment variables are gotten from a different place than shells use, because when you start an application by clicking on it, it instructs the Finder to start things up, and the Finder does not work through the conventional Linux-type shells.

For current versions of ipython there is a very easy workaround which takes care of the Canopy app since Canopy starts up ipython to run the code you are working on. This workaround should work under Windows as well, without any need to learn how to set environment variables under Windows.

In current installations of ipython, the user's home directory contains a configuration directory called .ipython . This will be created for the user by the Canopy app the first time it is run. (For other installations, it might be necessary to create the configuration files using the command ipython profile create ). Any Python scripts put in the directory .ipython/profile_default/startup will be executed whenever the user starts up ipython, either from the command line and via canopy. There can be as many startup scripts as you want in this directory, and they will be executed in lexical order by filename. To add, for example, the directory /home/MyModules to the search path import uses, you could create the file 00startup.py (or any other unused file name) in the directory .ipython/profile_default/startup , containing the lines:

import sys
sys.path.append('/home/MyModules')

You can also set environment variables in the startup script using the os package, e.g. to set the environment variable FOO to 'bar' you would use the lines:

import os
os.environ['FOO'] = 'bar'

however, I have not found this to work reliably for setting PYTHONPATH, whereas using sys.path.append always seems to work.

If you set the path in an ipython startup file, that will take care of ipython whether it is started up from the command line or via the Canopy app, even if the Canopy app is started up by double-clicking, and there is no need to also set the environment variables in the shell. However, since the plain python command line interpreter does not use the ipython startup files, you still need to set PYTHONPATH in the shell (or in Windows) if you want to be able to access modules in that path when starting up Python using the plain python command interpreter.

Note that sys.path.append can also be used within any Python script or interpreter session in order to temporarily modify the search path for modules for the duration of the session. This can be handy if you are using a Chapter Script that needs to make use of a script in some other chapter directory, but don't want that directory in the search path for every Python session.

back to top

About 32 bit vs. 64 bit (especially on Mac OSX)

Note: All current and recent Mac OS systems are 64 bit, so this section is only relevent for users running very old versions of the operating system. Pretty much the same goes for Windows and Linux users.

Before Mac OS 10.6, all applications were 32 bit. With OS 10.6, Apple began moving to a 64 bit world. OS 10.6 does not require all applications to be 64 bit, and 32 bit apps still run fine, but it permits 64 bit apps. This only impacts your world because Python itself is an app, and that means that if you are using a 32-bit version of Python, any add-on modules that use compiled code as opposed to straight Python (e.g. numpy, graphics modules and CliMT_lite) need to be compiled for 32-bit. Likewise, if you are using a 64-bit version of Python you need to use 64-bit compatible add-ons. This distinction does not apply to courseware utilities like ClimateUtilities.py or the Chapter Scripts, since they are in straight Python and do not have compiled components. For now, I recommend sticking with a 32-bit Python world, since precompiled 64-bit versions of the add-ons you need are not yet uniformly available. Be warned that the version of Python that comes shipped with Mac OS 10.6 and higher is a 64-bit Python, so using 32 bit on 10.6 and up means you need to install your own version of Python, which is recommended in any case.

The 32-bit vs. 64 bit distinction also exists on Linux, and on Windows.

On Linux and Mac OS, you can use the Linux command file to determine whether an application or compiled module is 32 bit or 64 bit. For example, the python shipped with my old OS 10.6 laptop is /usr/bin/python. If I go into a terminal window and type

file /usr/bin/python

I get the response:

/usr/bin/python: Mach-O universal binary with 3 architectures
/usr/bin/python (for architecture x86_64): Mach-O 64-bit executable x86_64
/usr/bin/python (for architecture i386): Mach-O executable i386
/usr/bin/python (for architecture ppc7400): Mach-O executable ppc

This means that this version is a "fat binary" which will work with either a 64 bit intel operating system (x86_64), a 32 bit intel operating system (i386) or the old Power PC chip (ppc7400). When you run this python, the most "advanced" version for your operating system will run. Under OS 10.6 that will be the 64-bit version. Under OS 10.5 that will be the 32 bit version. You don't get a choice. (Fat binaries including ppc code won't run on current versions of the Mac OS).

Now, on one of my earlier laptops, I installed the 32 bit Mac Python build. This installs with a link to /usr/local/bin/python . If I type

file /usr/local/bin/python

then I get the response

/usr/local/bin/python: Mach-O universal binary with 2 architectures
/usr/local/bin/python (for architecture ppc): Mach-O executable ppc
/usr/local/bin/python (for architecture i386): Mach-O executable i386

which means that this version is compiled without the 64 bit option. Therefore, it will run as 32 bit (i386) on an Intel chip Mac, even if you are on OS 10.6 (or presumably higher). On an old PPC Mac, it will run for that architecture.

Compiled libraries, which are part of certain Python add-on modules, also come in different architectures. Compiled libraries have the extension ".so" and are usually buried somewhere down in the directory tree for that module. For example, my installation of the module climt_lite , which I put in my modules directory, has a library climt_lite/_grid.so in it. So, if I go to my modules directory, and type

file climt_lite/_grid.so

the response I get is:

climt_lite/_grid.so: Mach-O bundle i386

which means this has been compiled for i386 (i.e. the 32 bit architecture). If I start up /usr/local/bin/python (which is the default on my system, as I can tell by typing which python) and then type import climt_lite into the interpreter, everything will work fine. On the other hand, if I start up the python shipped with Mac OS 10.6, which will run as 64 bit, and do the same import, I get the error message:

ImportError: dlopen(climt_lite/_grid.so, 2): no suitable image found. Did find:
climt_lite/_grid.so: mach-o, but wrong architecture

which is a bit cryptic, but all the important thing is "wrong architecture" which means that the library was compiled for an incompatible system. You'd get the same message if you tried to run an intel-only library on an old Power PC Mac.

back to top

About Dependencies

Some compiled extensions need to load shared libraries that are not part of the extension itself. If you try to import these and the library can't be found, either because it isn't installed or because it is installed in a place the system isn't looking, you will get an error message. For example, let's take one of my old versions of _grid.so which is a set of Fortran-compiled routines (a kind of library), which is imported by the climt package. If I try to import that on my current system in the Python interpreter, I get an error message:

>>> import _grid
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ImportError: dlopen(./_grid.so, 2): Library not loaded: /sw/lib/gcc4.2/lib/libgfortran.2.dylib
Referenced from: /Users/rtp1/CodeDevelopment/ClimtSandboxes/ClimtPrebuild/climt_lite/_grid.so
Reason: image not found

which is telling me that the library libgfortran.2.dylib wasn't found. (shared libraries on Mac or Linux are identified by the .dylib extension). This is a Fortran shared library, which is installed along with gfortran . I get this error message even though I actually have gfortran and its libraries installed, because, by default, the loader looks for libraries in the same place as they were when the compilation took place . In my case, I get the error message because I have since switched to a different gfortran installation, which put the libraries in a different place. Many developers avoid this problem by building what is needed from shared libraries into the compiled code, but sometimes this is impractical or difficult (we haven't yet figured out how to do that for the climt or climt_lite build, for example). You can find out what shared library dependencies any bit of code has by using the command line tool otool . Note that this is a shell command, not a Python command, and so it must be entered at a shell command prompt (under Linux or Mac OSX) not at a Python interpreter prompt. For example, the following tells us what dependencies _grid.so has:

rtp1% otool -L _grid.so
_grid.so:
/sw/lib/gcc4.2/lib/libgfortran.2.dylib (compatibility version 3.0.0, current version 3.0.0)
/sw/lib/gcc4.2/lib/libgcc_s.1.dylib (compatibility version 1.0.0, current version 1.0.0)
/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 111.1.4)

which gives the complete list of libraries needed. The earlier error message just gives the first library which couldn't be found, since the import command terminates at that point .

When a user builds something like _grid.so from scratch by compiling it, the libraries would automatically be searched for in the right place, but it saves the user a great deal of trouble in some cases if pre-compiled binaries can be distributed (e.g. the user would not need to install gfortran). Even if the user installed gfortran, the libraries would not necessarily be in the same place as they were when the developer compiled the code, and the libraries might not be compatible with the versions used when the code was compiled. One workaround is for the developer to distribute the necessary libraries together with the rest of the compiled binaries; then the user just needs to move the libraries to the place that otool -L says they are expected. Alternately, the libraries can be put in some other convenient place (e.g. the same directory as the package being distributed) and the search path for libraries can be modified using the environment variables DYLD_LIBRARY_PATH (on Mac OS X) or LD_LIBRARY_PATH (on Linux). This is what we will eventually do for distributing pre-compiled versions of the climt_lite package, at least until we can figure out how to link in the needed libraries inline. Note that setting path-related environment variables, like PYTHONPATH or DYLD_LIBRARY_PATH, within a Python session using os.environ evidently does not work. Such variables evidently need to be set within the shell before the Python interpreter is started, probably because setting the environment variables inside Python doesn't set them for the shell Python itself is running in.

back to top

 

Setting up a shared server for a class

If you are teaching a class using the courseware, you might find it convenient to install and run the courseware on a server that students can log into. This saves the trouble of guiding each student through an installation on their own computer, which can become particularly time-consuming given the range of different machines and operating systems you will encounter. In the early days of teaching using Python, I typically set up a class server so as to not have to deal with installation issues, but the Anaconda and Enthought distributions have made it so easy for students to install software on their own computers that it is rarely necessary to set up a class server anymore. Still, there are circumstances where running a server for the courseware can be convenient, since it means that students can do their work from any machine that can access the server, and shared data for the class to work on can be put in just one place without the need to distribute multiple copies. It is not hard to set up a class server under Linux, and even a Mac OS X machine can be used as a somewhat more limited courseware server. In either case, each student will need an account on the server. When using a Mac as a server, you need to go into the "sharing" preferences panel on the Mac you are using as a server and allow remote logins.

Back in the day, before the Web, the only way to access remote resources was to "log in" to another computer using some form of terminal program, and type in commands. This is still how most scientific computing is done. Many students these days are unfamiliar with the process, having never had to access remote resources except through a web browser. If they are going to do science, though, the sooner they learn about logging in and using basic Linux/Unix commands, the better. However, there is now a very powerful way to access Python on a server using only a web browser as the interface, via the ipython notebook feature. Notebooks can be used transparently to access python running locally on the student's own computer, and the behavior is much the same as if the notbooks are used to access Python running on a server. By far the best way to set up a shared Python server for a class is to use the jupyter notebook feature, which allows students to access the full power of Python through any web browser, with no special software needed on the student's computer. by setting up a notebook server, students can view graphics produced by their Python scripts without bothering with remote windowing systems such as X11 -- a convenience particularly for students with Windows computers. Most instructors should therefore skip directly to the notebook server instructions. The more antique methods are preserved below.

Logging in to a remote machine is done using the ssh command, which you type into a terminal window on either Mac or Linux. If you are interacting with Python using the command-line python or ipython interpreter, the standard Mac Terminal application (in the Applications->Utilities folder) will work fine, provided the Python commands you are running do not need to display any graphics on your Mac. On a Mac, you must be using an x11 terminal window instead if you want the server to be able to put up graphics on your screen. That includes use of the Canopy integrated development application, or the older IDE called idle, either of which must be able to draw graphics to handle its user interface. Up until recently, Macs shipped with an x11 terminal applicaton already installed, but on current Macs, you need to download and install it separately. It is available for free here. On Linux, every window is an x11 window, since x11 is the native windowing system for Linux. If you install the Enthought Canopy (or Canopy Express) distribution on a Linux server, then since the Linux version of the Canopy integrated development application uses x11 to put up its windows, a student accessing the server via x11 will be able to use the Canopy IDE just as if the server were their own machine. However, Canopy running on a Mac uses the native Mac windowing system, and therefore cannot put up windows on a remote machine. That also means that if you are using a Mac as the class server, it will not be able to put up any other graphics (except for graphic packages like PyNGL that use x11) on the remote machine either, if Python is accessed on the remote machine via a command line (but ipython notebooks provide a splendid workaround, as we'll see later).

Let's suppose the server is called snorkmaiden.umoomin.edu, and that your user id on that machine is hemulen. If you just want a plain text connection, from a Mac or Linux terminal window, you type

ssh hemulen@snorkmaiden.umoomin.edu

(If your userid on the local machine happens to be hemulen as well, you can leave off the "hemulen@" part.) You will then get a prompt for the password. After you enter your password, you will then get the command prompt for the server. Then you start entering commands, just as if you were running on your own machine. If you want a graphics connection, instead (from an x11 terminal window) you type

ssh -Y hemulen@snorkmaiden.umoomin.edu

The "-Y" flag tells the server that it should put up any graphics in a window on your own machine. On some older systems, you need to use "-X" instead.

Once you have established a connection to the server via ssh, any commands you issue run on the remote machine, and so far as the user is concerned function just as if the software were running locally on their own computer. The only little wrinkle you need to be aware of is that any files software running on the server accesses must be stored on the server. Similarly, any files you save from software running on the server will be saved in your directory on the server.

Mostly this is no problem, since the whole point of running on the server is that everything you need gets kept there, so you can get at it from any network-connected machine in the world. The one exception where you probably will want to move files to your own machine is when you want to save graphics or Python code for inclusion in a lab report or problem set. There are various ways to download files from your directory on the server. One way is to use the command scp or sftp, or (on older or insecure systems) ftp. Or, the instructor can set up a web server on the courseware server that automatically makes files in some special subdirectory of the user's home directory (typically www or public_html) accessible via a web browser. This is very convenient, since then you can put graphics for your problem set or lab report directly on the web, and not need to print them out. But if you just want to get some graphics in your report, the easiest thing is to just produce the graphics on your screen, and take a screen shot. Preview on a Mac does this very easily, and similar utilities are available on Linux and MS Windows. For putting Python code or text output into a file on your own machine, you can just copy from a Canopy window, idle window, or terminal window, and paste into a word processor document on your own machine.

ssh is available for MS Windows, but on Windows you don't generally start it by typing a command. Instead you double-click the terminal application, and enter the server and userid information in a dialog box. This gives you a plain text terminal connextion. The most common Windows terminal application is called putty, which provides ssh connections, and you'll need to download and install it if it isn't already present. If you want to see graphics, you will need a version of x11. Microsoft doesn't make this especially easy, which is one of the reasons Windows is not a suitable platform for serious scientific work. However, there is a fairly convenient (and free) third party x11 package called Cygwin, which you can download and install.

When using a shared class server, it is a good idea to put a copy of the ChapterScripts in a world-readable directory in the home directory on the server set aside for class resources (like data sets and courseware modules). This way, the students can just use the Canopy IDE on the server, open the ChapterScript they want using the Canopy open file dialogue box, and then save a copy on their home directory so they can modify it. Alternately, students can directly download chapter scripts from the Courseware portal, open in a text editor, and then copy and paste into a Canopy editor window.

When running the courseware on a server, you only need one copy of the shared courseware modules (ClimateUtilities.py, etc.), since these are not meant to be modified by the student. The courseware modules could be put in the site-packages directory for the Python installation, but since they are specific to just your course it is cleaner to put them in a directory of their own, located in the instructor's home directory or a course home directory. For example, if you put the courseware modules in the directory

/home/PlanetaryClimate/PlanetaryClimateModules

then to make the modules available to a user, it is necessary to include this in the Python search path by setting the $PYTHONPATH environment variable appropriately in the configuration file for the shell in use (read about shells and environment variables here). Note that each student needs to have their own copy of the shell configuration file in their home directory (e.g. .bash_profile for the bash shell). However, if this seems to complicated, there is no harm in each student putting their own copy of the courseware modules, put in their own modules directory in the place of their choice, in which case they can simply use the setpath.py utility in Courseware to set the paths.

Configuring the user environment under Enthought Canopy: The Enthought Canopy distribution is a bit different from the usual sort of Linux software distribution, since it makes use of an advanced "virtual environment" architecture that allows each user to customize their Python environment without affecting that used by the Canopy application or by other users. The instructor (or sysadmin) installs a master copy of Canopy in the place of choice, and each user's virtual environment is set up the first time they invoke the Canopy application. After the first use, the paths will be configured so that the user just needs to type canopy, python, or ipython at the command line in order to invoke the current Enthought versions, but the first time Canopy is started up, the user must type the full pathname of the Canopy app into the command line on most versions of Linux. (This issue doesn't arise when a student is running their own copy under Mac or Windows, since the application can be started up the first time by just clicking on the Canopy icon). All you need to do is to give the students the full pathname where Canopy is installed, and tell them to type it into the command line the very first time they long on, then follow the instructions. You can read about Canopy virtual environments under Linux here . Another, somewhat more complicated option, is to set up a system-wide Canopy install, as described here . That is less work for the student, but perhaps somewhat more work for the instructor or sysadmin.

Using idle on a shared machine:Since idle seems to be on its way out, and most users will be using the Canopy IDE instead (if they need an IDE at all), this information is only relevant for legacy installations. idle uses a trick to allow it to keep the Python interpreter which is running your script in a separate subprocess from the Python interpreter that is running idle itself. This trick, however, makes it impossible to run more than one instance of idle at a time on any given machine. If you are on a shared machine and try to start up idle on the command line while somebody else is running, you'll get an error message. When running idle on a shared machine, you should start up idle using the command idle -n instead, which runs without a subprocess. This has certain limitations that make it harder to work if you are developing complex software yourself, but for running the courseware the differences will be hardly noticable.

Using a Mac as a server:

Mac OS10 is basically a flavor of Linux, so it is possible to use an OS 10 box as a course server. You log on to a Mac using ssh the same way you would log onto any other Unix-flavored machine. Since PyNgl uses x11 for graphics, it can put up graphics on the user's machine across the network. However, most users will be using MatPlotLib graphics (which comes shipped with the Enthought Python distribution; this uses the native Mac windowing system, so it can't put up graphics across the network if you are using a Mac for the server. Similarly, the Canopy IDE application can't work across the network if you are running it on a Mac. It is possible for students to interact with Python running on a Mac server via a plain text interface, but if it is desired to interact with Python in a richer manner and for some reason you need to use a Mac as the class server, by far the best way to go is to use the ipython notebook feature, which will be described shortly.

By default, the Mac OS does not give permission for applications to "forward" x11 commands over the network. To enable this, you have to enable "x11 port forwarding." This isn't done through the System control panel. Instead you have to edit a line in a certain system configuration file (the inetd configuration file).

Using jupyter (formerly ipython) notebooks to access Python running on a server

jupyter (formerly ipython) notebooks are a brilliant new feature of the ipython interpreter. They allow the user to interact with ipython (running either locally or remotely) via a web browser. ipython notebooks allow users to execute python commands in an ipython interpreter from inside a web browser, but also can display graphical output and rich text (e.g. equations written in LaTeX) in the same browser window. I am gradually updating all my Python-based tutorials to exploit the power of notebooks, but for now you can read all about jupyter notebooks here, or get a quick-start introduction to their use here. By default, if you execute the command

ipython notebook

at a command line (on a computer with a recent Python distribution installed), it will run ipython on the local machine, and connect to the default web browser to put up a page allowing various ways of interacting with python.

There are three ways to allow users to run Python notebooks on a remote machine, without the need for installing Python on their own computers. The simplest (from the standpoint of the instructor) is to install a suitable Python distribution on a Linux machine on which students have accounts. The server must also have a web browser installed. The user than logs into the server using ssh, with X11 port forwarding enabled. Then when the ipython notebook command is issued at the server command ine, a browser window will pop up on the user's local computer, with the Notebook dashboard ready for use; the browser (and Python) are running on the server, but all graphics are re-routed to the user's computer. The main disadvantages of this method are that the student must be comfortable with ssh logins (a minor inconvenience) and must also have X11 or its equivalent running on their own computer (not a problem for Linux or Mac users, but a considerable headache for Windows users).

A much better way to provide access to Python via a server is to set up a jupyterhub server on the Linux server. Students still need to have accounts set up on the server, but they will then be able to log in to the server via an ordinary web browser pointed to a URL you specify when you set up the jupyter hub server. Graphics appear directly in a browser window, with no special additional screen-sharing software needed.

The third method is very geeky and cumbersome, and is preserved here mostly for historical reasons. You can set up an ssh tunnel from the local machine to a copy of ipython running on the server. This means that the user (e.g. student) needs to first start up their own ipython process on the server. These are the steps involved in using a local web browser to run ipython notebooks on a server, which we'll call snorkmaiden.umoomin.edu:

    1. The student (with userid hemulen on the server) logs in to snorkmaiden.umoomin.edu using their own account there and any convenient terminal application (even plain text).
    2. The student types in the command ipython notebook .
    3. This will start up ipython as a notebook server. On starting up, it will report various information, of which the most important is a phrase like: "The IPython Notebook is running at: http://snorkmaiden.umoomin.edu:8888/" In your case, the server name will be replaced by the actual name of the server you are using, and the number "8888" will be replaced by the actual "port" number that the notebook is "listening" to via the web browser.
    4. Then you set up the tunnel. On a Mac or Linux this is done from a command line using the command: ssh hemulen@snorkmaiden.moomin.edu -L8999:localhost:8888 , where "8999" can be any unused port on the local machine and "8888" is replaced by the actual port used by the ipython notebook server. A password will be requested. After this is entered, the tunnel starts up and an ipython notebook startup page should appear in the student's web browser. Then the student points the browser to the URL http://localhost:8999 , and the Python notebook dashboard should show up. Note that any notebooks the student saves will be saved in the student's directory on the server, not on the local machine.

back to top