Setting up

These instructions are intended for someone new to python and juypyter. If that’s not you, just get a copy of the pesto scripts from gitlab and skim read the rest of this page. You are better off downloading from the repository than cloning, since the presence of large files in the example_data folder have made the git commit history files quite large.

_images/downloadButton.png

By far the simplest approach to getting a working environment is to download the Anaconda distribution for Python 3, which will automatically configure your computer with python, Jupyter and nearly all required packages (numpy, matplotlib etc). This is around a 500mb download and will require around 5.5Gb free space to install.

Intructions for Windows users

Get Anaconda

Download and install the Anaconda distribution for Python 3.x. Accept the default options while installing.

Install missing packages

Anaconda comes with most of what you’ll need, but some things are still missing. All of the packages listed below can be installed from the ‘Anaconda Prompt’ with the indicated command.

package

Purpose

Consequence if missing?

Command to install

ipympl

Interactive plotting back-end

Interactive data viewers don’t work

pip install ipympl

igor

Loading igor binary files

Can’t load Scienta SES output files

pip install igor

lmfit

Peak fitting

fitFermiEdge unavailable

pip install lmfit

nbextensions

Usability tweaks for the notebook

Notebooks less convenient

conda install -c conda-forge jupyter_contrib_nbextensions

pyperclip

Putting content into the system clipboard

Can’t generate template code cells

pip install pyperclip

Important note regarding the igor package: New installations of this are broken due to syntax changes in newer versions of NumPy, and you will see an error message when pesto tries to import it. To fix this, you need to find and edit binarywave.py. The error message will tell you where it is located, but the default location in Windows is C:/Users/(your user account)/AppData/Roaming/Python/Python311/site-packages/igor. Find the TYPE_TABLE declaration and change the line:

1:_numpy.complex, #NT_CMPLX, makes number complex.

to:

1:complex, #NT_CMPLX, makes number complex.

Put the pesto files somewhere

Get the latest version from gitlab. You don’t need git to do this, you can just download everything as a zip file. Put it somewhere on your computer that all your notebooks will be able to point to.

Start a Jupyter notebook server

These notebooks require a server to be running in the background in order to bring them to life. Launch one from the Anaconda prompt by typing:

cd \
jupyter notebook

A new page should automatically open in your default web browser. It’s like a file browser but for Jupyter notebooks - notice that it’s showing you the contents of whatever directory the Anaconda prompt was in.

_images/setup_browser.png

If you typed `cd `, this is probably `C:`. In the Jupyter file browser you can go deeper into sub-folders, but *you can’t navigate ‘up’ out of the directory you launched it from*. That’s the reason for moving up to the root directory with the `cd ` command before launching the Jupyter notebook server.

Immediately underneath the Jupyter logo is a set of tabs, with the ‘Files’ tab currently selected. Hopefully the rightmost tab is ‘Nbextensions’; click on this to start configuring notebook extensions.

_images/setup_extensions.png

On the ‘Nbextensions’ page, first uncheck the box which says ‘disable configuration for nbextensions without explicit compatibility’.

You can use whatever extensions you like, but for pesto the following three are recommended: (‘Codefolding’, ‘Collapsible Headings’, ‘Table of Contents (2)’)

When selecting the ‘Table of Contents (2)’’ extension, scroll down and also check the option ‘Display toc window/sidebar at startup’

Make a new notebook

Go back to the ‘Files’ tab and navigate to wherever you have the experimental data you want to work with. Once you’re there, make a new notebook with the ‘New’ button in the upper right corner. Select ‘Python 3’

_images/setup_newnotebook.png

You’ll then be taken to that notebook in a new tab:

_images/setup_newnotebook2.png

Import the pesto library into a notebook

Copy the following into an empty code block, change the pestoDirectory line to point to where the pesto folder is located and execute the block:

from pathlib import Path
import sys
#Define the path where the pesto files is stored - you will need to change this to match wherever you put them!
pestoDirectory = Path('C:/Users/your_name/pesto')
sys.path.insert(0, pestoDirectory)
import pesto

import matplotlib.pyplot as plt
import matplotlib,math,numpy as np

from IPython.display import display, HTML
display(HTML("<style>.container { width:75% !important; }</style>"))

# Plot formatting
font = {'size'   : 14}
matplotlib.rc('font', **font)

%matplotlib widget

If all goes well, you should see some output about the pesto version:

_images/setup_importOK.png

It’s also perfectly fine to just put a copy of the pesto folder alongside every notebook instead of having one central copy that every notebook refers to. In this case, the import block becomes much simpler:

import pesto
import matplotlib.pyplot as plt
import matplotlib,math,numpy as np

from IPython.display import display, HTML
display(HTML("<style>.container { width:75% !important; }</style>"))

%matplotlib widget

If you get an error “No module named ‘pesto’”, double check that you have given the correct path to the pesto folder. Getting the import directory correct is a common source of trouble. If you downloaded the files from gitlab and have now have them on your computer as (for example) C:/pesto-master/pesto, the pestoDirectory you would use in the above example would be C:/pesto-master, not C:/pesto-master/pesto.

To elaborate slightly: The line import pesto works if the notebook can see a folder called ‘pesto’ that contains the core files (e.g. base.py). Those files have to be in a folder named ‘pesto’, and that directory can’t be nested in a sub-sub directory. For example:

├── base.py
├── __init__.py
├── notebook.ipynb
└── XPS.py

–> Calling import pesto from this notebook.ipynb will fail, because it can’t see a ‘pesto’ directory

├── notebook.ipynb
└── pesto

├── base.py
├── __init__.py
└── XPS.py

–> Calling import pesto from this notebook.ipynb will work

├── notebook.ipynb
└── pesto

└── pesto

├── base.py
├── __init__.py
└── XPS.py

–> This will fail, because it will look inside only the first ‘pesto’ directory and it won’t immediately find the files it needs in there.

You’re now set up and ready to go. Browse the rest of these pages if you need a reminder of what functions are available to you in pesto.

** Bonus optional extra: Open notebooks by double clicking on them:**

It can be inconvenient having to always open the Anaconda Terminal and type ‘jupyter notebook’ when you want to work with a notebook. The solution in place on the Bloch computer involves the nbopen package, which allows you to double click on an existing notebook in windows explorer. The github page has straightforward two-step instructions for installing and configuring it.

Linux (Ubuntu)

Largely the same as for windows, with the following notes:

  • The Anaconda package you download will come as a *.sh file. Install from the terminal with (for example) bash ~/Anaconda3-5.0.1-Linux-x86_64.sh

  • Commands can be issued from the default terminal instead of the Anaconda prompt

  • In the header block, when pointing to a central pesto installation use:

from pathlib import Path
import sys
#Define the path where the pesto library is stored - you will need to change this to match your installation!
home = str(Path.home())
sys.path.insert(0, home+'/path/to/pesto/')
import pesto
  • The pyperclip module may require you to install xclip before it will work. Install from the terminal with sudo apt install xclip

Mac

Installation of Anaconda is straightforward. Use the same header block as in the linux section.

Comments

Jupyter, python and matplotlib are enormous, pre-existing projects. If you have non-pesto questions about them, you’ll find a nearly infinite supply of very good documentation and tutorials online.

Plotting style: The default matplotlib backend in jupyter notebook is ‘inline’. In some circumstances you might prefer to set this style, e.g. when rendering final images for reports or publications. Change the backend using %matplotlib inline or %matplotlib widget. The setting will persist through the whole notebook, and you can switch back and forth as often as you like.